Commerce Foundation Operation Sequences

Microsoft Multi-Channel Commerce Foundation request processing components are grouped into operations. The Commerce Server 2009 broker controls the execution of the operation through the Microsoft Multi-Channel Commerce Foundation operation sequence. The operation sequence of the operation must contain one or more components to handle the operation.

Operation Sequence Component

To create a component of the specific type, you must implement the IOperationSequenceComponent interface. Microsoft Multi-Channel Commerce Foundation defines the following interface for this purpose.

public interface IOperationSequenceComponent 
{
   void Execute( CommerceOperation operation, 
                 OperationCacheDictionary operationCache, 
                 CommerceOperationResponse response);
}

Or, you could create an operation sequence component that simply inherits from the OperationSequenceComponent class. This will provide strongly typed operation methods along with all of the necessary tracing capabilities.

Parameter	Description
operation	Represents the current operation being processed by the broker.
operationCache	The operationCache is a string-to-object dictionary that can be used in a manner similar to how the ASP.NET Cache is used. Only, it does not store objects between operation invocations, but rather between the invocations of the components that belong to the same operation. This cache object allows the Microsoft Multi-Channel Commerce Foundation operation sequence components to share expensive resources during the operation execution. For example, in the product query scenario the ProductLoader retrieves one or more products from the Commerce Server database and translates them into the Commerce Server 2009 products that become part of the operation response. After the operation sequence component finishes its job it stores the retrieved Commerce Server products in the Cache. This enables a subsequent operation sequence components to easily retrieve these Commerce Server products from the cache rather than from Commerce Server to perform its specific task - for example supplying the product cross-sell or up-sell or variants etc.
response	Response object passed to each component. The response object is created by the Broker based on the responseType configuration attribute.

The operation sequence execution starts with the first operation sequence component and moves through them iteratively in the order defined in the configuration. A Microsoft Multi-Channel Commerce Foundation operation can have any number of components defined for the operation sequence. You can customize the business rules of an operation simply by manipulating the content of the operation sequence by either replacing components or add your own. All the components in the operation sequence can be replaced and any number of the components can be added to it as long as you implement the IOperationSequenceComponent interface.

Commerce Foundation Operation Configuration

An example of the configuration section that defines a Microsoft Multi-Channel Commerce Foundation operation is shown below. The configuration sections reflect the object model described above. A MessageHandler contains the OperationSequence that consists of one or more components defined in a hierarchical format.

<MessageHandler name="CommerceQueryOperation_Product"
responseType="Microsoft.Commerce.Contracts.Messages.CommerceQueryOperationResponse, Microsoft.Commerce.Contracts, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
  <OperationSequence>
    <Component name="Product Query Processor" type="Microsoft.Commerce.Providers.Components.ProductLoader, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
      <Component name="Cross-Sell Provider" type="Microsoft.Commerce.Providers.Components.ProductCommerceServerRelationshipProcessor, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
        <Configuration
          customElementName="CommerceServerRelationshipConfiguration"
          customElementType="Microsoft.Commerce.Providers.Components.CommerceServerRelationshipConfiguration, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
          <CommerceServerRelationshipConfiguration commerceServerRelationshipName="CrossSell" internalRelationshipName="CrossSells"/>
        </Configuration>
      </Component>
      <Component name="Up-Sell Provider" type="Microsoft.Commerce.Providers.Components.ProductCommerceServerRelationshipProcessor, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
        <Configuration
            customElementName="CommerceServerRelationshipConfiguration"
            customElementType="Microsoft.Commerce.Providers.Components.CommerceServerRelationshipConfiguration, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
          <CommerceServerRelationshipConfiguration commerceServerRelationshipName="UpSell" internalRelationshipName="UpSells"/>
        </Configuration>
      </Component>
      <Component name="Product Variant Provider" type="Microsoft.Commerce.Providers.Components.ProductVariantProcessor, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35"/>
      <Component name="ProductAncestorCategoryProcessor" type="Microsoft.Commerce.Providers.Components.ProductAncestorCategoryProcessor, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35"/>
      <Component name="ProductCanonicalCategoryProcessor" type="Microsoft.Commerce.Providers.Components.ProductCanonicalCategoryProcessor, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35"/>
      <Component name="ProductParentCategoryProcessor" type="Microsoft.Commerce.Providers.Components.ProductParentCategoryProcessor, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35"/>
      <Component name="ProductPrimaryCategoryProcessor" type="Microsoft.Commerce.Providers.Components.ProductPrimaryCategoryProcessor, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35"/>
      <Component name="ProductRelatedCategoryProcessor" type="Microsoft.Commerce.Providers.Components.ProductRelatedCategoryProcessor, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35"/>
      <Component name="ProductRelatedProductProcessor" type="Microsoft.Commerce.Providers.Components.ProductRelatedProductProcessor, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35"/>
      <Component name="ProductInventoryItemsProcessor" type="Microsoft.Commerce.Providers.Components.ProductInventoryItemsProcessor, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35"/>
      <Component name="Product catalog relationship" type="Microsoft.Commerce.Providers.Components.ProductCatalogRelationshipProcessor, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35"/>
      <Component name="Product base catalog relationship" type="Microsoft.Commerce.Providers.Components.ProductBaseCatalogRelationshipProcessor, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35"/>
      <Component name="Product Discounts Relationship" type="Microsoft.Commerce.Providers.Components.CatalogEntityDiscountsProcessor, Microsoft.Commerce.Providers, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35" />
    </Component>
  </OperationSequence>
</MessageHandler>

In the MessageHandler element, the name attribute maps an incoming operation request to the appropriate Microsoft Multi-Channel Commerce Foundation operation sequence, whose component classes process the request and generate the response. The name of a Microsoft Multi-Channel Commerce Foundation MessageHandler consists of two parts separated by an underscore character. The first part is the name of the operation type and the second part is the model name of the commerce entity upon which the operation is performed.

The name of the operation is obtained from the Name property of the Type object for the operation of the request. This name is stripped of any namespace information. This allows you to use the same configuration sections for the operations that handle the requests that are based on the classes derived from the Operation as long as the name are the same as the Microsoft Multi-Channel Commerce Foundation class. The namespace of course should be different from the Microsoft Multi-Channel Commerce Foundation namespace. However, if you decide to use different names for the derived types you will have to change the MessageHandler names in the configuration file.

The Component can be expressed as a hierarchy that represents the dependencies between the components. In the example shown, all components depend on the Product Query Processor component.

The following are the MessageHandler element attributes:

Attribute	Description
responseType	The responseType attribute tells the Broker which response class to instantiate via reflection. The response is always created by the Broker and updated by the operation sequence components.
name	Identifies the operation and commerce element handled by the message handler.

The following are the OperationSequence element attributes:

Attribute	Description
Transactional	Indicates whether the operation sequence is transactional.
TransactionIsolationLevel	Specifies the isolation level for the operation sequence transaction. Valid values include Serializable, RepeatableRead, ReadCommitted, ReadUncommitted, Snapshot, Chaos, and Unspecified.
TransactionTimeout	Specifies the time out for the operation sequence transaction.

The following are the Component element attributes:

Attribute	Description
name	The name attribute is a short name given to the operation sequence component. It must be unique across all operation sequence components of the operation.
description	The description attribute is only intended for human consumption and is used to improve the readability of the operation configuration.
type	The most important attribute of the Component element is type. It fully defines the type of the corresponding component. Commerce Server 2009 uses its value to dynamically instantiate the component through the Reflection mechanism. The type attribute format follows the standard .NET way to specify a class type in the configuration file. It should contain comma separated strings. The first string is a fully qualified name of the class that is prefixed with all the namespaces. The second one is the name of the containing assembly, which optionally can be followed by the assembly version, the culture and the public key token.
TransactionalScopeOption	Indicates the transaction scope, the options are: OptionDescription None (default)No transaction support is defined or created. RequiredParticipates in the existing transaction. If no transaction is present, a new transaction will be created. RequiresNewThe component executes within a new transactional scope. SuppressThe component executes in a non-transactional scope.
TransactionIsolationLevel	Specifies the isolation level for the operation sequence transaction. Valid values include Serializable, RepeatableRead, ReadCommitted, ReadUncommitted, Snapshot, Chaos, and Unspecified.
TransactionTimeout	Specifies the time out for the component transaction.

The following are the Configuration element attributes:

Attribute	Description
customElementName	The name of the XML element that contains configuration for the operation sequence component. An XML element with this name must be a child of the Component element.
customElementType	The ConfigurationElement type that will be used to load the operation sequence component configuration.

The classes specified through the type attribute of the Component element must implement the proper interface described above. If the types registered as components in the Operation section fail to implement the proper interface, the InvalidCastException will be thrown during runtime. Every operation component must have a public default (parameterless) constructor.

Commerce Foundation Broker Interpretation of the Operation Sequence

The Broker is a key component of Commerce Server 2009 that maps an incoming request to the Microsoft Multi-Channel Commerce Foundation operation and executes the corresponding operation sequence that processes the request and generates the operation's response.

In order to do so, the Broker implements the following algorithm:

1. The Broker creates the OperationCacheDictionary object. See the sections below on how the operation components can use the OperationCacheDictionary.

2. Based on the type of the CommerceOperation objects in the CommerceRequest being processed, the Broker creates the response object.

3. The Broker checks the type of the Request object and the type of the model contained in this object to determine the name of the message handler operation responsible for handling this request.

4. If this is the first time the operation is to be executed, the Broker loads the operation sequence component type information from the configuration file (see the previous section on the details of the operation configuration) and stores it in the internal cache. Dependency checking is performed at this point.Otherwise, on the subsequent calls to the operation, the Broker retrieves the operation component type information from the internal cache.

5. Using the type information obtained in the previous step, the Broker instantiates all the configured operation sequence components using the Reflection mechanism.

6. The Broker begins a transaction if the operation sequence has been configured as transactional.

7. The Broker invokes, in turn, each component in the order defined in the configuration file.

8. The Broker finishes the execution of the operation by returning the Response object updated by the operation sequence components.

In This Section

• Commerce Foundation Transactions

See Also

Other Resources

Developing with the Multi-Channel Commerce Foundation

Commerce Foundation Transactions

Commerce Foundation Operation Sequence Extensibility Point