How to Create and Deploy a Custom Operation Sequence Component

Custom operation sequence components can be used to extend Commerce Server 2009.  An operation sequence is a chain of one or more components that perform an operation on a CommerceEntity of a particular model.  There are 5 types of operations, they are: Created, Delete Query, and Update.  In addition these may be extended and you may create your own operation.  See the CustomOperationSequenceComponents project of the Extensibility solution for a complete code sample.

Note This sample code is provided to illustrate a concept and should not be used in applications or Web sites, as it may not illustrate the safest coding practices. Microsoft assumes no liability for incidental or consequential damages should the sample code be used for purposes other than as intended.

Hardware and Software Assumptions

You can access the sample code by selecting them in the samples folder you selected when you installed the Microsoft Commerce Server 2009 SDK Samples. In order to use these samples it is assumed that you have installed the following:

• Microsoft Visual Studio 2008 SP1

• Microsoft Internet Information Services (IIS)

• Microsoft Commerce Server 2009

• Microsoft Commerce Server 2009 SDK Samples

Visual Studio Solution Structure

The Extensibility.sln solution is composed of the following project:

Building the Solution

Within Visual Studio:

1. Open the solution file Extensibility.sln

2. Right click on Solution "CustomOperationSequenceComponents.csproj"

From the context menu select Build Solution.

Project Details

To implement a new component that plugs into the Multi-channel Commerce Foundation Operation Sequence one have an option to either create a class that implements the Microsoft.Commerce.Broker.IOperationSequenceComponent interface or a class that derives from the Microsoft.Commerce.Providers.Components.OperationSequenceComponent class. The latter is more convenient since the developer can focus on only implementing the operations that are relevant for his or her component by overriding one of the following virtual methods:

• ExecuteQuery

• ExecuteCreate

• ExecuteUpdate

• ExecuteDelete

In the SDK sample project CustomOperationSequenceComponents a custom component was created using the following steps:

1. Create a new class, CustomOperationSequenceComponent, that derives from the Microsoft.Commerce.Providers.Components.OperationSequenceComponent.

2. Since this component is only responsible for handling the query operation, override the ExecuteQuery method.

3. In the ExecuteQuery, examine the Microsoft.Commerce.Contracts.Messages.CommerceQueryOperation parameter to decide if the query contains a request for the data that the components are responsible to provide. If the query is relevant to the component, the component retrieves the data and populates the response.

4. Create a library that extends the Microsoft.Commerce.Providers.Components.OperationSequenceComponent. The following component extends the Product model, adding a CountryOfOrigin property to the Query operation:

   public class CustomOperationSequenceComponent : OperationSequenceComponent
       {
           /// <summary>
           /// This operation sequence component populates the custom Product property "CountryOfOrigin"
           /// </summary>
           /// <param name="queryOperation">The query operation.</param>
           /// <param name="operationCache">The operation cache.</param>
           /// <param name="response">The response.</param>
           public override void ExecuteQuery(CommerceQueryOperation queryOperation, OperationCacheDictionary operationCache, CommerceQueryOperationResponse response)
           {
               // check if the request model is asking for the property which this custom component is responsible for populating
               if (queryOperation.Model.ModelName == "Product" &&
                           queryOperation.Model.Properties.ContainsProperty(Product.PropertyName.CountryOfOrigin))
               {
                   // loop over all products loaded by the ProductLoader operation sequence component 
                   // which meet the query's SearchCriteria and populate the CountryOfOrigin property
                   foreach (CommerceEntity product in response.CommerceEntities)
                   {
                       product.Properties["CountryOfOrigin"] = GetCountryOfOriginById(product.Id);
                   }
               }
           }
     
           private static string GetCountryOfOriginById(string productId)
           {
               // this would normally be an outside data source like a DB or service call
               if (Convert.ToInt32(productId.Substring(2, 3)) > 100)
               {
                   return "USA";
               }
               else
               {
                   return "Canada";
               }
           }
       }
   

5. Add a reference to said component for the desired combination of operation type and model type to the ChannelConfiguration.config. In order to extend the Query(CommerceQueryOperation) sequence for the Product model above add add the following entry to the <MessageHandler name="CommerceQueryOperation_Product"> node.

   <Component name="Product Country of Origin Processor"
              type="Microsoft.Samples.Commerce.CustomOperationSequenceComponent, 
              CustomOperationSequenceComponents, Version=1.0.0.0,
              Culture=neutral,PublicKeyToken=28810a541a11b484"/>
   

   Note Operation Sequence Components are executed sequentially, and therefore one component may have a dependency on another. The CustomOperationSequenceComponent adds a CountryOfOrigin property to all Products in the response object.  That is all products that meet the search criteria which were loaded into the response object by the "Product Query Processor" operation sequence component. This dependency should be expressed by placing the "Product Country of Origin Processor" node below the "Product Query Processor".

6. For the new component to be successfully loaded by the Multi-channel Commerce Foundation during runtime the assembly that contains the component class has to be strongly named.