How to Extend Commerce Server

Article
11/17/2011

Custom operation sequence components can be used to extend the Microsoft Microsoft Multi-Channel Commerce Foundation API. An operation sequence is a chain of one or more components that perform an operation on a CommerceEntity of a particular model. There are 4 types of operations, they are: Create, Delete, Query, and Update. This sample shows how to create a custom operation sequence that can be used to augment the properties of a product by injecting a custom property "country or origin" taken from an alternate data source.

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.

Prerequisites

You can access the sample code by extracting the .zip archive in the samples folder you selected when you installed the Commerce Server 2009 R2 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

Unpackage and Configure the PUP

You must first unpackage and configure the included Commerce Server site via the PUP file "SolutionStorefrontWithSampleData.pup".

The samples depend upon the data within this package.

To create the Commerce Server site

In Windows Explorer, navigate to the <dir>\Pup Packages.
Double-click the SolutionStorefrontWithSampleData.pup file.
In the Unpack screen, select Quick Unpack, and then click Next.
In the Quick Unpack screen, ensure that the SQL Server computer name is correct, enter the SQL Server login name and password or select Windows Authentication as the authentication method, and then click Next.
In the Profiling System screen, accept the defaults, and then click Next.
In the second Profiling System screen, accept the defaults, and then click OK.
In the Commerce Server Site Packager dialog box, click OK.
In the Unpacking is complete! screen, click Finish.

The Commerce Server site is unpacked to the Solution Storefront in IIS.

Building the Solution

You will have to build the ExtensibilityAPIUsage.sln before proceeding.

To build the solution within Visual Studio

In Windows Explorer, go to <dir>\Extensibility Kits\Samples\.
Unzip the FoundationSamples.zip to a new directory.
Browse to the Extensibility folder.
Double-click the ExtensibilityAPIUsage.sln file. This opens the solution in Visual Studio.
Under Solution Explorer, right-click Solution <solution name>, and from the context menu select Build Solution.

Creating a Web Application

Use the following steps to add the sample application to your Commerce Server site in Internet Information Services (IIS). When you do so, you will choose an IIS application pool to assign to the Web application. To make sure that the application works correctly, the application pool you select must comply with the following:

The application pool must have all the necessary security privileges to access your Commerce Server site and its associated databases.

To add the application to the Commerce Server site in IIS 7.0

In Internet Information Services (IIS) Manager, in the navigation tree, click Sites, right-click Default Web Site, and then click Add Application.
In the Alias box, type a name for your sample.
Click the Select button next to the Application pool box, select the application pool to use, and then click OK.

Note

The application pool must have all the necessary security privileges to access your Commerce Server site and its associated databases.
In the PhysicalPath box, type the full path of the application. This is the path to which you browsed to the FoundationSamples\Extensibility folder.

For example, when you extract the FoundationSamples.zip to the same folder, the application path is as follows: %commerce_server_root%Extensibility Kits\Samples\FoundationSamples\Extensibility:
Click OK.
In Internet Explorer, go to the following URL to access the Web application:

https://localhost/<your_sample_vdir>/Default.aspx,

where <your_sample_vdir> is the value used in step 4.

Creating and Deploying a Custom Operation Sequence Component

To implement a new component that plugs into the Multi-channel Commerce Foundation Operation Sequence you can either create a class that implements the Microsoft.Commerce.Server.IOperationSequenceComponent interface or create a class that derives from the Microsoft.Commerce.SequenceComponents.Components class. The latter is more convenient since you can focus on only implementing the operations that are relevant for the new component by overriding one of the following virtual methods:

ExecuteQuery
ExecuteCreate
ExecuteUpdate
ExecuteDelete

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

Create a new class, CustomOperationSequenceComponent that derives from the Microsoft.Commerce.SequenceComponents.Components.
Since this component is only responsible for handling the query operation, override the ExecuteQuery method.
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.

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

{
            // Raise a Fault if for whatever reason the query or the response is null
            ParameterChecker.CheckForNull(queryOperation, "queryOperation");
            ParameterChecker.CheckForNull(response, "response");

            // check if the request model is asking for the property which this custom component is responsible for populating
            if (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 (Product product in response.CommerceEntities)
                {
                    product.CountryOfOrigin = GetCountryOfOriginById(product.Id);
                }

                //// without wrappers
                ////foreach (CommerceEntity product in response.CommerceEntities)
                ////{
                ////    product.Properties["CountryOfOrigin"] = GetCountryOfOriginById(product.Id);
                ////}
            }
        }
        #endregion

        /// <summary>
        /// Gets the country of origin by id.
        /// </summary>
        /// <param name="productId">The product id.</param>
        /// <returns>The country of origin.</returns>
        private static string GetCountryOfOriginById(string productId)
        {
            ParameterChecker.CheckForNullOrEmpty(productId, "productId");

            // this would normally be an outside data source like a DB or service call
            if (Convert.ToInt32(productId.Substring(2, 3), CultureInfo.InvariantCulture) > 100)
            {
                return "USA";
            }
            else
            {
                return "Canada";
            }
        }

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 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".
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.