Commerce Foundation Channel Configuration

Article
01/18/2011

The Microsoft Multi-Channel Commerce Foundation is designed to be an extensible framework which allows you to extend or complete replace any of the existing operations, as well as introduce new operations within the Microsoft Multi-Channel Commerce Foundation service. You can also extend existing commerce entities or introduce new ones. When you make a change to your site, you will have to update the Commerce Server 2009 Channel Configuration file ChannelConfiguration.config in order for your site to implement your change.

Configuring a new Web Site

Upon the creation of a new Commerce Server 2009 site within SharePoint, you will be required to enter the channel name and the default catalog to be used in the site. This is done via a custom SharePoint List that is created when adding the site and enabling Commerce Server 2009 features. To promote discoverability of this task, the web parts will render a message indicating that the channel and catalog must be configured. Additionally, the top node in the site map provider will supply this message to make it obvious.

Assembling the Site or Deploying an existing WSP

After the site has been configured via these options, you can begin assembly of the web site (or alternately install from an existing template). If you decide to add a web part to the site before you have configured the channel name and default catalog, the web part(s) will render an error message indicating that the channel and/or default catalog have not yet been configured.

Channel Management

The Channel Management SharePoint list contains four (4) default options:

DefaultCatalog
Channel
LiveApplicationID
LiveApplicationSecret

These options cannot be deleted, they're mandatory for the site. You can extend this list, adding your own options which could then be utilized by custom code. However, the out of the box site only the default options will appear in this list. The DefaultCatalog and Channel are mandatory and need to be configured before the web part will function. The LiveApplication fields are to provide support for Windows Live Id integration. By default all fields are set to empty values at feature activation time.

Extending the Channel Configuration SharePoint List

There are times when you will need to extend the channel configuration options. This would occur through the creation of a custom content type within SharePoint and associating that type to the Channel Configuration list in SharePoint. This process will allow you to support data types other than "string" (which is the default column type in the list out of the box).

Error Conditions

1) The value in the "title" column acts as the primary key, and thus there cannot be duplicate entries within the list

2) The list must contain at least two content types - one for the "title" field and another for the value

3) The Channel and Default Catalog entries cannot be deleted from the list as these are required for Commerce Server 2009

Enabling the Feature

Enabling the feature is the point where the Channel Management SharePoint List will be created within the web site. This process will:

Create the SharePoint List
Register an event handler with the SharePoint list
Populate the SharePoint list with the Channel and Default Catalog entries
Create a content type to be used with the SharePoint list

This feature will be packaged as part of the Commerce Server 2009 WSP and the event handler will be tied to the SharePoint list.

Projects

The feature has two main projects.

One project (ChannelConfigFeature) defines a SharePoint Feature with event handler. The event handler is responsible for synchronizing the values of the SPList with the SPWeb property bag. It does so with the aid of a class called SPWebPropertiesHashtable. SPWebPropertiesHashtable implements IDictionary and is a helper to reading and writing from the property bag. A web part may use SPWebReadPropertiesHashtable. SPWebReadPropertiesHashtable provides read-only access to the property bag. SPWebReadPropertiesHashtable is defined in the second project, ChannelConfigLib. The aim of SPWebReadPropertiesHashtable and SPWebPropertiesHashtable is to abstract the particulars of the implementation of the configuration storage. SPWebPropertiesHashtable writes to SPWeb's property bag by prefixing the keys with a "namespace" - microsoft.commerce.settings - , so as to avoid collisions with any other user-defined entries. SPWeb provides caching and replication across the farm.

At any given time, the list may only have content types with two columns. One of which must be Title. The rule may be enforced with the FieldAdding event and a second event handler.

Reading Configuration

Commerce Server 2009 web parts may include a reference to the ChannelConfigLib and use the SPWebReadPropertiesHashtable class to read configuration. Keys and values are strings. This will be managed via the existing SiteContext class within the Commerce Server 2009 projects.

ChannelConfiguration.config

The first line of the ChannelConfiguration.config specifies if the Commerce Server is to user Shared Commerce Contexts.

<ServiceConfiguration useSharedCommerceContexts="true">

A value of true indicates that CommerceContext.Current will be available, and used by all operation sequence components. Context objects exposed through the CommerceSiteContexts class will refer back to the context objects exposed through CommerceContext.Current. This also means that only a single site can be configured in ChannelConfiguration.config.

A value of false indicates that CommerceContext.Current will be null, and not used by any operation sequence components. A separate set of Commerce Server context objects will be created for each site configured in ChannelConfiguration.config. These can be accessed through the CommerceSiteContexts class. Some features may not be available in this configuration mode. For example, the Default Site will not work with useSharedCommerceContexts=false because it relies on the Commerce Server UPM membership provider for user authentication.

Note

Currently only "true" is supported, meaning that Commerce Server 2009 is running as a shared Commerce Server resource.

Sites

While not supported in this release, if you want to run Commerce Server 2009 in non-shared mode (specifically userSharedCommerceContexts'"false"), you must allow Microsoft Multi-Channel Commerce Foundation to initialize all Commerce Server contexts in order to use them within Commerce Server 2009. To do this you will have to specify each context within the ChannelConfiguration.config file, under the <Sites>.

Note

This is only required in non-shared mode, which is outside the context of IIS.

  <Sites>
    <Site sitename="SampleSite" disableProductVersionHttpHeader="true" metadataRepositoryPath=".\SampleSiteMetadataDefinitions.xml">
      <authentication detectCookies="true"/>
      <pipelines>
        <pipeline
          name="basket"
          path="pipelines\basket.pcf"
          transacted="false"
          type="OrderPipeline"
          loggingEnabled="false" />
 …
      </pipelines>
      <caches>
        <cache
          name="Advertising"
          type="Advertising"
          refreshInterval="850"
          retryInterval="30" />
…
      </caches>
      <messageManager>
        <cultures
           default="en-US"
           baseName="CommerceMessageManager"
           assembly="CommerceMessageManager">
          <culture id="en-US"/>
          <culture id="fr-fr"/>
          <culture id="ja-JP"/>
          <culture id="de-DE"/>
        </cultures>
        <resources>
          <resource id="pur_badsku"/>
          <resource id="pur_badplacedprice"/>
          <resource id="pur_discount_changed"/>
          <resource id="pur_discount_removed"/>
        </resources>
      </messageManager>
      <catalog  enableInventorySystem="true">
        <catalogSets
           defaultAuthenticated="Registered User Default CatalogSet"
           defaultAnonymous="Anonymous User Default CatalogSet" />
        <cache
           enable="true"
           schemaTimeout="20"
           itemInformationCacheTimeout ="20"
           itemHierarchyCacheTimeout ="20"
           itemRelationshipsCacheTimeout = "20"
           itemAssociationsCacheTimeout="20"
           catalogCollectionCacheTimeout="20" />
      </catalog>
…
    </Site>

Translators

There are two child elements for Translators: ToCommerceEntities and ToExternalEntities, which are specified under <Translators>.

The ToCommerceEntities child element must include the following attributes:

Attribute	Description
sourceType	Specifies the Commerce Server source type.
destinationModelName	Specifies the name that will be used within Microsoft Multi-Channel Commerce Foundation.
type	Specifies the translator used to map between Commerce Server and Microsoft Multi-Channel Commerce Foundation.

The ToExternalEntities child element must include the following attributes:

Attribute	Description
sourceModelName	Specifies the name that will be used within Microsoft Multi-Channel Commerce Foundation.
destinationType	Specifies the Commerce Server destination type.
type	Specifies the translator used to map between Commerce Server and Microsoft Multi-Channel Commerce Foundation.

Operation Sequences

Operation sequences are specified as <MessageHandlers>, and must include the following attributes:

Attribute	Description
name	The name of the operation sequence, which must follow a specific order, specifically: <operation>_<commerce_entity> Where <operation> is the type of operation such as CommerceQueryOperation or CommerceUpdateOperation, and where <commerce_entity> specifies the commerce entity onto which the operation is being performed such as Site or Basket.
responseType	The object that will process the response.

name

The name of the operation sequence, which must follow a specific order, specifically:

Where <operation> is the type of operation such as CommerceQueryOperation or CommerceUpdateOperation, and where <commerce_entity> specifies the commerce entity onto which the operation is being performed such as Site or Basket.

responseType

The object that will process the response.

For example:

<MessageHandler name="CommerceQueryOperation_Site" responseType="Microsoft.Commerce.Contracts.Messages.CommerceQueryOperationResponse, Microsoft.Commerce.Contracts, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
        <OperationSequence>
          <Component name="Site Processor" type="Microsoft.Commerce.Providers.Components.SiteLoader, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35" />
          <Component name="Site Catalogs Processor" type="Microsoft.Commerce.Providers.Components.SiteCatalogsProcessor, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35" />
        </OperationSequence>
</MessageHandler>

Commerce Server Pipelines

Commerce Server allows you to create your own pipelines using PCF files. In order to execute these pipelines in Microsoft Multi-Channel Commerce Foundation they must be added to the ChannelConfiguration.configand contain the following attributes:

Attribute	Description
name	The name attribute should contain one of the Order pipeline names defined in the pipelines section of the CommerceServer site configuration.
type	Specifies the Commerce Server source type. The type attribute should contain one of the values of the Microsoft.Commerce.Providers enumeration, for example Microsoft.Commerce.Providers.Components.OrderPipelinesProcessor.

For example, an Order pipelines configuration may look like this:

<Component name="Order Pipelines Processor" type="Microsoft.Commerce.Providers.Components.OrderPipelinesProcessor, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
  <Configuration
    customElementName="OrderPipelinesProcessorConfiguration"
    customElementType="Microsoft.Commerce.Providers.Components.OrderPipelinesProcessorConfiguration, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
    <OrderPipelinesProcessorConfiguration>
      <OrderPipelines>
        <Pipeline name="basket" type="Basket"/> <!--  Indicates a Basket pipeline (e.g. Basket.pcf) -->
        <Pipeline name="total" type="Total"/>   <!--  Indicates a Total pipeline (e.g. Total.pcf)   -->
      </OrderPipelines>
    </OrderPipelinesProcessorConfiguration>
  </Configuration>
</Component>