Max Akbar : Orders System

Reach out and touch Messagemanager

Max Akbar — Sat, 10 May 2008 17:55:47 GMT

If you are creating your own pipeline components and your site is international and you need more than the four languages that is out of the box German, French, Japanese and US English for Commerce Server then you need to create your own resource for other languages. How to create a new resource is what this post is all about.

What is Messagemanager?

Messagemanager is an object that handling the localization of messages inside your pipeline competents. When you unpack the CSharpSite you will get CommerceMessageManager.dll and four folders representing a language mentioned above.

What are these messages that Messagemanager use? The table below has the messages that Commerce Server uses internally. If you introducing a new language then you need to localize this table.

Message Key	Message Value
pur_discount_changed	One or more discounts have changed.
pur_badhandling	Unable to complete order: cannot compute handling cost.
pur_badsku	Please note that one or more items were removed from your order because the product is no longer sold.
pur_badtax	Unable to complete order: cannot compute tax.
pur_badplacedprice	Please note that prices of products in your order have been updated.
pur_badcc	The credit-card number you provided is not valid. Please verify your payment information or use a different card.
pur_badshipping	Unable to complete order: cannot compute shipping cost.
unknown_shipping_method	The selected shipping method is not currently available. Please choose another shipping method.
pur_badpayment	There was a problem authorizing your credit. Please verify your payment information or use a different card.
pur_out_of_stock	At least one item is out of stock.
pur_noitems	An order must have at least one item.
pur_badverify	Changes to the data require your review. Please review and re-submit.
pur_discount_removed	One or more discounts no longer apply.
L_Language_DisplayName	English (en-US)

OK I have localized the messages now what?

You need to take the localized messages and create an assembly. There are many methods the following help file link should help. Once you create an assembly then you need to add it into your bin folder, take care to create the language folder then add the assembly there.

Can I add my own messages?

Yes, but the help files do note that the messagemanager is obsolete (I wonder why then Commerce Server uses it? If you find the answer let me know :))?

How to use Messagemanager inside of Pipeline Components?

If you have created your own messages and want to use it inside your custom pipeline components the following code will accomplish that.

// using message manager inside pipeline component
IMessageManager messageManager = null;
IDictionary dict = (IDictionary) pContext;
messageManager = (IMessageManager) dic["MessageManager"];
object message = messageManager.GetMessage("your string key", language);

In order for the pipeline to use the specific language you must execute the Pipeline by passing the language code in the PipelineInfo object. If the language parameter is not specified, or is NULL, the message is returned for the message set identified by the DefaultLanguage property of the MessageManager object. This value is retrieved from the web.config under the messageManager element.

Are we there yet?

Once you have done all the above you will need to add the language in the web.config of your site. Why do I need to do this? We need to tell Commerce Server's Pipeline processor that we have a new language so when Commerce Server pipelines encounter an error they retrieve the message correctly.

Will my custom component also work automagically? No, see the code above about messagemanager and notice that we are passing the language and since you set this value in the PipelineInfo object it will be accessible through the pipeline via the context (pdispContext) parameter.

OK, I think we are done now.

OrderForm Visualizer

Max Akbar — Tue, 29 Apr 2008 06:52:38 GMT

Have you developed a pipeline component and then started to debug it and found that you couldn't drill down the OrderForm, Dictionary and SimpleList objects? Well here is the solution. I created this Visualizer to help with the debugging process of pipeline components.

What is a Visualizer?

Visualizers allows the displays of a variable or object in a meaningful way. For example, if you have a DataSet visualizer interprets a DataSet object and displays the result in a DataGridview. So the OrderForm visualizer interprets Commerce Server OrderForm which inherits from Dictionary and SimpleList in a TreeView. After installing the OrderForm visualizer run your pipeline code and set a debug point bring your cursor on the object you wish you view noticed that now you have a Dictionary Visualizer.

After selecting the visualizer the data is rendered in a TreeView.

You can now visualize the data in a tree structure by viewing the key\pair value and the data type.

Note: The OrderForm visualizer does not allow modifying the underlying data.

What Version of Visual Studio 2005 does this support?

Edition	Visual Basic	C#	C++	Web Developer
Express	X	X	Managed only	X
Standard	X	X	Managed only	X
Pro and Team	X	X	Managed only	X

I haven't tested Visual Studio 2008 but I don't see any issues with using it.

Where do I get the OrderForm Visualizer?

Commerce Server Training, Inc.

PayPal is looking for a few good customers :)

Max Akbar — Thu, 07 Feb 2008 06:51:44 GMT

PayPal has just announced that they are looking for a few early adopters. If you want to test their component developed for Commerce Server then follow the instruction on their blog site.

Do you use Microsoft Commerce Server 2007? - PayPal Developer Blog - PayPal Developer Community

Support for SQL replication of the profiles and of the transactions database

Max Akbar — Wed, 19 Dec 2007 19:38:12 GMT

I wrote a blog a while ago that Commerce Server SP1 with SQL 2005 SP2 supported replication with Profiles and transaction database. Now I can confirm that this is a supported scenario here is the KB Article. I am disappointed that the KB article does not walk the user step by step and setting up your profiles and transactions database but at least you know it's supported scenario.

What about replication of other Databases?

Marketing, Product Catalog, Transaction Config and Inventory is supported by use of Import\export APIs and\or using Commerce Server Staging.

Why Use replication?

Multiple data centers for backup and redundancy.

How To Deal With Large Orders And Improve Checkout Performance

Max Akbar — Sun, 02 Dec 2007 22:54:57 GMT

There are some scenarios were you need to handle 100 or more line items and performance becomes an issue. So in this post I hope to provide you with some ideas on how you can speed up the performance of the Checkout path.

Checkout Path

What is the checkout path? The checkout process starts from the moment the users enter the basket\cart page. Then, they navigates to shipping and billing page. This can either be one page or two. Next, they receives a confirmation page and finally, the users checks out and navigate to the receipt page.

Basket Display

This page shows the user what is in their basket. Usually the line item id, description, total line item cost, any discounts, total and subtotal. Bellow is an example:

Item ID	Description	Cost	Quantity	Discount	Total
123-ABC	My product description	$10.00	1	$1.00	$9.00
Subtotal					9.00

You can also allow the user to enter promotion codes here if you site allows it.

The Basket pipeline file is executed in the page.

Basket Pipeline File

The Basket pipeline validates the line item product and removes any line items that does not validate again the Product Catalog System. Inventory is also checked. Pricing variables are initialized and used later on in the discount stage. Finally the subtotal is calculated.

Billing and Shipping Information

Some sites will have Billing and Shipping information on one page and some have it in two. These pages allows the user to select an address from their address book or enter a new one. The addresses can be used for shipping or shared as billing address. The billing section will also allow the user to enter a credit card.

This page executes the Basket and Total pipeline files.

Total Pipeline File

The Total pipeline computes the amount of an order and calculates Shipping, Handling, Tax, Order Total. This pipeline will also calculates any shipping discounts that need to be applied.

Confirmation Page

The confirmation page allows the user to validate their order before accepting the purchase. This page displays the line items and addresses for shipping and billing, payment methods and discounts applied.

This page executes Basket and Total pipeline files.

Receipt Page

The receipt page is an exact duplicate page as the confirmation page that shows that the order has been purchased.

This page executes Basket, Total and Checkout pipeline files.

Checkout Pipeline File

The Checkout pipeline is responsible for redeeming promotion codes, decrement inventory, record Content Selection framework events, and finally the events are appended to the IIS log.

What about Add to Basket\Cart?

On some sites when the user adds an item to the basket they are redirected to the basket page like the Starter Site and some sites display a simple message that the item was added to the basket. The sites that don't redirect the user need to only validate the product against the Product Catalog System. To do this you only need to execute the Product pipeline component.

Product Pipeline File

Product pipeline validates that the product is in synch with the Product Catalog System.

Why are we executing the pipelines over and over?

Because the user can wait indefinite time between pages and prices, products or discounts could be invalid we need to execute the pipelines to ensure the accuracy of the basket before converting it to purchase order.

What happens when I execute a pipeline?

Commerce Server basket has several entities such as OrderForm, LineItems, Addresses, Shipments to name a few. These objects are based on .NET. The Commerce Server Processing Pipeline is COM. When a pipeline is executed the managed objects in the basket need to be converted into a dictionary. Commerce Server does this for you before executing the pipeline file. When the execution of the pipeline is completed, the process is reversed. If you are interested in a detailed explanation of pipelines then I suggest you read the following posts.

How to improve performance?

Do not use scriptor pipeline Components. Scriptor Component is good for quick and dirty proof of concept.
When creating custom pipeline Components then enable pooling for your pipelines.
Follow the basics of .NET performance coding techniques. Here is a couple of reads for you Improving ASP.NET Performance, Improving Interop Performance and Improving Managed Code Performance.
Don't create Commerce Contexts inside your custom pipelines pass them as pipeline Context values.
When adding items to the basket don't redirect the user to the basket page. Imagine if 25 percent of your users add more than one item to their basket, now you are executing the basket 25 more times then necessary.
Don't iterate the lineitems object then get a Commerce product object, the lineitem is filled with all it's properties in the Product Info of basket pipeline stage, try to use what's there.
Remove unwanted pipeline components, for example if you are not using the Inventory System then remove the CheckInventory and Update Inventory.
If you don't have or not using the data warehouse then you can remove the CSFRecordEvent and CSFIISAppendToLog.
Create one pipeline component for each page, this will reduce the transformation of .NET object to COM and back. For example you would create a BillingShipping.pcf that has the combined basket and Total files and the same is true for the receipt page.
Don't keep to many weakly types because most of your time will be spent in serialization when they are stored in the marshalled data field.
Add business logic that if the lineitem collection is more than 50 or whatever your business requirements are then execute them offline. This would mean that you have to create an application that runs large orders for you.
If your business can't support this scenario then keep one server available for large order scenario. When you detect large orders then redirect the checkout process to another server that does nothing but handle large orders.
If your business allows then don't execute the basket pipeline stages during the shipping and billing only the Total as you will catch any issues when the users tries to complete the purchase.

If you have additional ideas please post a comment for others.

Do you have your eye on it CS2007 SP1

Max Akbar — Fri, 22 Jun 2007 10:13:06 GMT

Commerce Server 2007 Service Pack 1 is due out end of June if all goes well :), keep your eye on it. There are two things note worthy:

Replication of Orders and Profiles Database

This was a design change request that was introduced right after the product went live so a lot of testing wen into it. The replication will allow to have more than one Data Centers acting as active active. If one data center goes down the other can pick up the load. Should be interesting to read all the details on how to do this.
Using Tabular functions for Catalogs SetJoin API

I am very proud of this as I had a hand in it :). I had my hand in lots of cookie jars when I was at Microsoft, still do ;). Originally the product only supported tables and views to be joined with the Product object. Some scenarios made it impossible to use the SetJoin API. Imagine if you had dynamic pricing scenario, you could write a function that runs a select statement based on parameters you passed it and the product API would then return you some results that you could then perform validations and selecting the correct price. What if you needed to search a table before the join occurred? Well now you can. I am very eager to see how this is implemented and how people will use.

And they say Microsoft doesn't listen to it's customers :). I am very proud to have been part of the product group developing such a great software. Make sure to read every little bit of what's new.

PayPal: What's New and What's Next - PayPal Developer Blog - PayPal Developer Community

Max Akbar — Thu, 14 Jun 2007 08:04:09 GMT

Here is some good news for those who are looking for PayPal integration. Apparently the PayPal team is looking to integrate with Commerce Server and are going to release something this fall for Commerce Server 2007 and 2002 for more information check out the PayPal developer blog.

Payment Modules Coming this fall:

Microsoft Commerce Server 2007 & 2002 versions

PayPal: What's New and What's Next - PayPal Developer Blog - PayPal Developer Community

How to enable pipeline pooling

Max Akbar — Wed, 09 May 2007 00:14:08 GMT

I was asked by a few folks on how do you create poolable pipeline components? After talking with David Messner, I learned that all you need to do is create a category and mark it appropriately. We seem to document this “PooledPipeline Object” but missing a few key items. We are missing the C++ header file mspu_guids.h that has the guid for the CATID_MSCSPIPELINE_POOLABLE constant and we are missing the instruction on tagging the component poolable. After lots of investigation I figured out what the guid is by looking at Commerce Server 2002 mspu_guids.h file:

// 4cb33c86-58fa-4e10-97a8-f19aff3b81d9

DEFINE_GUID( CATID_MSCSPIPELINE_POOLABLE,

0x4cb33c86,0x58fa,0x4e10,0x97,0xa8,0xf1,0x9a,0xff,0x3b,0x81,0xd9);

Next I searched Commerce Serve 2007 pipeline components registry values and we tag our pipeline components category with this guid.

This has been entered as bug and we will document it better in the future, but if you want poolable components you need to add a registry entry under the Implemented Categories with the guid stated above. Something else that may help in automating the registration process is a documentation Registering the ATL Component for Commerce Server 2002.

Digonex Technologies Dynamic Pricing System to be Available to Microsoft Commerce Server Users Via an Adapter for BizTalk Server

Max Akbar — Mon, 09 Apr 2007 18:12:09 GMT

Link to Digonex Technologies Dynamic Pricing System to be Available to Microsoft Commerce Server Users Via an Adapter for BizTalk Server

OrderForm Viewer 2007

Max Akbar — Sun, 24 Sep 2006 01:34:00 GMT

The long awaited OrderForm Viewer for Commerce Server 2007 is now released get your copy from GotDotNET.

Have fun,

-Max

Everything you ever wanted to know about pipelines but were afraid to ask (Part IV)

Max Akbar — Thu, 21 Sep 2006 07:10:00 GMT

So far you if you have followed this on going Pipeline posts, you should be very familiar with how to work with pipelines how to configure them using Pipeline Editor, how to manage your pipelines in the web.config as well as creating your own custom pipelines. I also hinted that you can use some undocumented APIs to automate some administration tasks (of course since this is undocumented its not supported :p). You should also be very familiar with creating custom UIs for your custom pipeline components and saving it's data.
As promised in this post I will show you how to debug your custom components and do how to test them and this will conclude the final post.

Before we jump into this I would like to offer you some readings, the UE team for CS2007 have done a fantastic job at documenting this version of Commerce Server so in a very nice way I would like to say please take a moment and make sure that you "Read The Fine Manual" :). Should you not agree I encourage you to take a moment and send feedback using the help docs.

There are two other great blog post that you should read David Messner's Transactional pipeline components and error handling and Nihit Kaul's Running Pipelines in a Console Application.

Creating PropertyPages for your Pipeline Component

This is a bit off topic but if you are like me you want to know everything there is to know when developing and dealing with Pipelines. So I have been asked how do you create a property page for the pipeline components. The short answer is that you can not create a property page using .NET. You will have to develop with C++. Here is how:

We are going to work with what you have created so far in the previous posts. So launch your Custom Pipeline Project.
Now that you have Visual Studio up and running with our project Select File then Add and next select New Project...
Form the Add New Project dialog navigate and select C++ then ATL and in the right pane select ATL Project.
Enter a descriptive name for the project then select OK.
From the ATL Project Wizard dialog select Next.
From the ATL Project Wizard dialog Application Settings make sure that only Dynamic-Link Library (DLL) radio button is selected and next select Finish.
The wizard will create two projects see image below.

Now you need to implement the ISpecifyPropertyPages Interface. This interface has only one method you need to implement GetPages. This interface is implemented in your custom pipeline component class.

using System;
using System.Collections.Generic;
using System.Text;

using System.Windows.Forms;
using System.Runtime.InteropServices;
using Microsoft.CommerceServer.Interop;
using Microsoft.CommerceServer.Interop.Orders;
using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Orders;
using Microsoft.CommerceServer.Internal;

namespace CustomPipeline
{
    [ComVisible(true)]
    [GuidAttribute ("5904C354-F1B8-485c-89DD-883D26BCE85D")]
    public class Class1 : IPipelineComponent,
            IPipelineComponentAdmin,
            IPersistDictionary,
            ISpecifyPipelineComponentUI,
            IPipelineComponentDescription,
            ISpecifyPropertyPages

//.......
// code commented out for clarity
//.......

#region ISpecifyPropertyPages Members

    public void GetPages(out tagCAUUID pPages)
    {
        throw new Exception("The method or operation is not implemented.");
    }

#endregion

//.......
// code commented out for clarity
//.......

Select your ATL Project and right click then select Add and next select Class.
From the Add Class Wizard navigate to ATL then from the right pane select ATL Property Page and select the Add button.
In the ATL Page Wizard enter a descriptive name for your class then select Next.
In the next page make sure that Apartment Threaded for Thread Modeling is selected and No for Aggregation then select Next and finally select Finish.
The wizard will create a basic Property Page.
In the ATL project Select the project resource file and double click. This will bring you the Resource View.
FrFrom the Resource View navigate to Dialog and double click our newly created property page.
Next drag and drop a text box and use the existing Static Text.

Now we need to add some code to the GetPages method to display our property page.

public void GetPages(out tagCAUUID pPages)
{
    pPages = new tagCAUUID();

    pPages.cElems = 1;
    byte[] buffer1 = new Guid("{2879AC98-0A80-4F6B-AC0C-EE8A1E0391E3}").ToByteArray();
    pPages.pElems = Marshal.AllocCoTaskMem(buffer1.Length);
    for (int num1 = 0; num1 < buffer1.Length; num1++)
    {
        Marshal.WriteByte(pPages.pElems, num1, buffer1[num1]);
    }
}

The GUID must be of that of your property page. You can get this by opening the .rgs file of your property page.

Now build your solution.
Run the steps for registering your custom component with pipereg.exe.
TeTest your new Property Page in Pipeline Editor.
Congratulation you have now created a new property page for you pipeline component.

How to Use MessageManager

Take a moment to read the following help topic How to Use MessageManager. This topic will help you localize your error messages.

Error Handling in Pipelines

Take a moment and read the following help topic Error Handling in Pipelines. . This will familiarize you with where to add errors so you can display it to the user.

Troubleshooting Pipelines

Debug pipelines in ASP.NET

To debug your pipelines in ASP.NET unpackage the CSharp site and set the correct security permissions.
Open the Custom Pipeline Solution.
Right Click on your Solution and add a Existing Web Project and select CSharpSite.
Modify the CSharpSite's Web.config so you can execute the basket pipeline.
Modify the basket pipeline and add your custom pipeline anywhere (make sure that you had compiled your code in debug mode).

Now add code to the default.aspx page to execute your basket pipeline.

Basket basket = CommerceContext.Current.OrderSystem.GetBasket(Guid.NewGuid());
basket.OrderForms.Add(new OrderForm());

PipelineInfo pipeinfo = new PipelineInfo("basket");

PipelineExecutionResult pipeResult = basket.RunPipeline(pipeinfo);
Response.Write(pipeResult.ToString());

Note: You should know how to do the above steps for a refresher please read the previous posts.

Now add the custom pipeline dll and pdb files under the bin directory of your CSharp Site.
Now go to your Custom Pipeline project and create a breakpoint anywhere under the Execute method.
Check the web.config to make sure it's set for debugging:

<application siteName="CSharpSite" debugLevel="Debug"/>

and

<compilation defaultLanguage="c#" debug="true">
Launch Internet Explore and navigate to the CSharpSite default.aspx page (For the advanced folks you can do the next steps by adding the URL in the debug properties of your project).
Now in your Visual Studio select the Debug menu then select Attach to Process...
In the Attach to Process dialog find the w3wp.exe process and attach to it (your Visual Studio solution will now be in debug mode).
Refresh your Internet Explorer.
Notice that you now hit your breakpoint.

Using the XMLTracer Pipeline Component

David Messner originally wrote the Troubleshooting Commerce Server Pipelines and in that article he wrote the XMLTracer that has now made it's way into the product. You can read more about the XMLTracer here.

How to Debug the Scriptor Component

As a best practice never use the scriptor component for production use. You can however use the DumpOrder.vbs for debugging pruposes or only use the scriptor for proof of concept applications. Please read the documentation for How to Use the Scriptor Component. To setup the scriptor debugging please read David Messner's article Troubleshooting Commerce Server Pipelines chapter 3.

Using Pipeline Logging

This section of the help files will guide you through How to Use an Order Log.
When you set the loggingEnabled section of the pipeline make sure to create a folder under the pipeline folder called log and give ASP.NET access to write\read\modify.

Using the Scriptor to dump pipeline values to a file

In my second post I mentioned the DumpOrder.vbs file, you can also find more information about it here.

Test your Pipelines

Since you have written your pipeline component in .NET testing becomes very simple all you have to do is write a test that calls the execute method. Make sure to read Nihit Kaul's Running Pipelines in a Console Application.

Pipeline Performance

The pipeline performance counters are used for performance monitoring and tuning. The object name for the performance counters is Commerce : Pipelines. Counter instances are created per site, per a pipeline and pipeline component (.pcf file) combination. You will first need to execute your pipeline before you can collect data.

Summary

Now you know all there is to know about pipelines, good luck.

Everything you ever wanted to know about pipelines but were afraid to ask (Part III)

Max Akbar — Sun, 17 Sep 2006 22:35:00 GMT

So far you should be comfortable working with pipeline files creating\modifying components and having a good understanding of basic concepts of creating a custom pipeline components and as promised lets dive deeper into advanced understanding of the pipeline interfaces.
Then we will dive into the Order System and learn about the heart of pipelines OrderForms.

Pipeline Interfaces

In order to create pipeline components you need to implement one or more interfaces. You must always implement the IPipelineComponent Interface, without this Interface the pipeline component will not execute. All other Interfaces and exposes other functionality to fit into the Commerce Pipeline architecture.

IPipelineComponent Interface

As have been noted this Interface must be implemented in order for the pipeline object to execute the component.

The IPipelineComponent interface supports the following methods:

Execute
The entry point at which the pipeline begins executing the component.
The following is the method signature for the Execute Method:

int Execute(object pdispOrder, object pdispContext, int lFlags);

The Execute method contains three parameters:
pdispOrder - A pointer to the OrderForm object.
pdispContext - A pointer to the Context object. This is a Dictionary object that contains pointers to the MessageManager object, Content object, and language information. Values can be passed through this parameter using the PipelineInfo object.
lFlags - Reserved. This parameter should be zero (0).

The Execute method also returns an integer parameter. A flag that indicates what level of errors is tolerated.
1 Success. No errors, component executed successfully.
2 Warning. Basket or purchase errors for this operation.
3 Failure. Serious errors in execution of this component.

The following sample shows how to pass Context values to the Pipeline object.

Basket basket = CommerceContext.Current.OrderSystem.GetBasket(userID);
PipelineInfo pipeinfo = new PipelineInfo("Basket");

pipeinfo["OrderContext"] = CommerceContext.Current.OrderSystem;

basket.RunPipeline(pipeinfo);

The following code shows how to retrieve the Context passed into the Pipeline.

A best practice is always put a try\catch in Execute Method so when exceptions do occur you can set the correct return value, see the following sample (you may also want to log the exception):

public Int32 Execute(Object pdispOrder, Object pdispContext, Int32 Flags)
{
    Int32 ReturnValue = StatusSuccess;

    // Status level for component execution
    try
    {
        // perform some logic
        // you also can set a warning
        // ReturnValue = StatusWarning;
    }
    // an error has occured. Add the error message to the basket errors and
    // set the "error" as the pipeline component error level
    catch (Exception e)
    {
        ((ISimpleList)Order["_Basket_Errors"]).Add(ref e.Message);
        ReturnValue = StatusError;
    }
    return ReturnValue;
}

EnableDesign
Sets the design mode on the component. Use this method to prepare the component for execution in one of two modes: design mode or execution mode. In design mode, which is useful for running the Pipeline Editor, errors are more easily tolerated. Execution mode (the default) is analogous to production mode. Although you have to Implement the EnableDesign method you can leave it empty.

void EnableDesign([In] int fEnable);

IPipelineComponentAdmin Interface

The IPipelineComponenetAdmin Interface allows you to save configuration values at design time and they are read at runtime to perform some action based on your logic. For example in the MinMaxShipping sample a UI is presented when editing the component in Pipeline Editor and you set thresholds of minimum shipping cost. Once this value is set during the design time and when the pipeline executes, this value can be used to make sure we don't fall below the shipping cost. In order to show the properties for MinMaxShipping the sample uses a WinForm that implements IPipelineComponentUI Interface, this is an alternative to using the ISpecifyPropertyPages Interface. After going over some concepts of the other Interfaces I will show you an example of how these Interfaces work together.

The IPipelineComponenetAdmin Interface supports the following methods:

GetConfigData
Returns a Dictionary object that contains the configuration settings for a component.
The following is the method signature for the GetConfigData
Method:

object GetConfigData();

The GetConfigData method returns an object parameter. The object returned is actually an IDictionary pointer for the user interface to read the configuration data for the component.
SetConfigData
Sets the configuration settings on a component using the contents of a Dictionary object.
The following is the method signature for the SetConfigData.

void SetConfigData(object pDict);

The SetConfigData method contains one parameter:
pDict - An interface pointer to the object containing the configuration information.

IPipelineComponentUI Interface

The IPipelineComponentUI Interface is implemented to allow a pipeline component to display a dialog box for configuration values. The interface is implemented by a separate Component Object Model (COM) object that displays the dialog box in .NET this can be a WinForm. In order to display the WinForm you must also implement the ISpecifyPipelineComponentUI. The ISpecifyPipelineComponentUI specifies the WinForm to launch which executes the ShowProperties method.

The IPipelineComponentUI interface supports the following method:

ShowProperties
Called by the Pipeline Editor to display the dialog box for the component.
The following is the method signature for the ShowProperties:

void ShowProperties(object pdispComponent);

The ShowProperties method contains one parameter:
pdispComponent - A pointer to an IPipelineComponentAdmin interface.

IPersistDictionary Interface

The IPersistDictionary Interface is implemented by an object that needs to read or write its data as a Dictionary object. When creating a UI for your pipeline may have need to save it's data if so then use the IPersistDictionary Interface. The configuration data is saved within the Pipeline Configuration File.

The IPersistDictionary Interface supports the following methods.

GetProgID
The following is the method signature for the GetProgID.

object GetProgID();

Returns the ProgID of the object.
InitNew
Allows the object to initialize values before saved values are loaded.
The following is the method signature for the InitNew.

void InitNew(object pDict);
IsDirty
Indicates whether the values to be saved have changed since the last save.
The following is the method signature for the IsDirty.

void IsDirty(object pDict);
Load
Loads saved data from a Dictionary object.
The following is the method signature for the Load.

void Load(object pDict);
Save
Saves data to a Dictionary object.
The following is the method signature for the Save.

void Save(object pDict);

IPipelineComponentDescription Interface

The IPipelineComponentDescription Interface makes it possible for pipeline components to identify the values that they read from the pipeline context, and the keys and values that they read from or write to the OrderForm object.

Although pipeline components are not required to implement the IPipelineComponentDescription Interface, implementing this interface makes it possible for the Pipeline Editor to identify and display the elements that your component reads or writes. This information can help developers who are troubleshooting a pipeline configuration.

The IPipelineComponentDescription interface supports the following methods.

ContextValuesRead
Returns a SAFEARRAY VARIANT that identifies the pipeline context values that the component reads.

object ContextValuesRead();
ValuesRead
Returns a SAFEARRAY VARIANT that identifies the values that the component reads.

object ValuesRead();

ValuesWritten
Returns a SAFEARRAY VARIANT that identifies the values that the component writes.

object ValuesWritten();

An Example of how to write SAFEARRAY VARIANT in .NET to work with the Pipeline Component:

object ValuesWritten()
{
    object[] valuesWritten= new object[3];

    valuesWritten[0] = "myValue_1";
    valuesWritten[1] = "item.myValue_2";
    valuesWritten[2] = "_myValue_3";

    return valuesWritten;
}

ISpecifyPipelineComponentUI Interface

The ISpecifyPipelineComponentUI Interface is used by a pipeline component to specify the Component Object Model (COM) object that implements the IPipelineComponentUI interface that gets and sets configuration values.

The ISpecifyPipelineComponentUI Interface supports the following method.

GetPipelineComponentUIProgID
Used by the pipeline component to specify the component that displays the configuration dialog box by implementing the IPipelineComponentUI Interface.

object GetPipelineComponentUIProgID();

Here is an example of the above method:

public string GetPipelineComponentUIProgID()
{
return "CustomPipeline.Form1";
}

ISpecifyPropertyPages Interface

The ISpecifyPropertyPages Interface is a standard Win32 OLE interface. You implement this interface to allow the pipeline administration tool to invoke the property page user interface of the component. For more information about the ISpecifyPropertyPages Interface, see the OLE Programmer's Reference.

The ISpecifyPropertyPages Interface supports the following method:

GetPages
Fills in an array of class identifiers (CLSID) where each CLSID is the CLSID of a property page that can be displayed in the property sheet for this object.

Now let's put it all together with an example:

We are going to work on the sample component created for the last post.

Launch Visual Studio 2005
Open the CustomPipeline Project from our previous post
Add a WinForm
- Right Click on CustomPipeline Project and add a new Form
- Name your Form something descriptive.
- Add two buttons, a Lable and a TextBox to the Form
  This form will be used to store custom data during the design time and extract during the runtime for processing.
- Set Form properties:
  StartPosition=CenterScreen
  FormBorderStyle=FixedDialog
  MaximizeBox=False
  MinimizeBox=False
Add IPipelineComponentUI Interface to WinForm and implement it's interface
Implement the IPipelineComponentUI Interface

By selecting the Implement interface 'IPipelineComponentUI' you will get the following code:

#region IPipelineComponentUI Members

public object ShowProperties(object pdispComponent)()
{
throw new Exception("The method or operation is not implemented.");
}

#endregion
Add a new variable to the Form

bool OK = false;

Add details to OK and Cancel Button's Click Event
When Clicking the OK Button we want to save the configuration else do not save the Sample Data.

private void button2_Click(object sender, EventArgs e)
{
    SamlpleData = this.textBox1.Text;
    this.OK = false;
    this.Hide();
}

private void button1_Click(object sender, EventArgs e)
{
    this.OK = true;
    this.Hide();
}

Now we need to add a property to the form.
We need to get values out and in from the WinForm when values are entered.

public string SamlpleData
{
    get
    {
        return Convert.ToString(textBox1.Text);
    }
    set
    {
        textBox1.Text = value.ToString();
    }
}

Add implementation details for IPipelineComponentUI's ShowProperties method:
In order to retrieve and save values during design time we need to add code to the ShowProperties method.

try
{
    // Use IPipelineComponentAdmin Interface to get configuration information
    IPipelineComponentAdmin pdispPCA = (IPipelineComponentAdmin)pdispComponent;

    // Populate a dictionary with component configuration
    Microsoft.CommerceServer.Runtime.IDictionary dictConfig = (Microsoft.CommerceServer.Runtime.IDictionary)pdispPCA.GetConfigData();

    Form1 frmPipeCompUIObj = new Form1();

    // Get the sample data
    frmPipeCompUIObj.SamlpleData = (String)dictConfig["SampleData"];

    // Display the properties for the user to editbr
    frmPipeCompUIObj.ShowDialog();

    if(frmPipeCompUIObj.Ok)
    {
        // Save entered values into the dictionary
        dictConfig["SampleData"] = frmPipeCompUIObj.SamlpleData;

        // Update the component with new configuration information
        pdispPCA.SetConfigData(dictConfig);
    }
}
catch(Exception e)
{
    throw(new Exception(e.Message));
}

Repeat Step 4 and 5 with IPersistDictionary Interface for our Component (These Interfaces must be implemented in your component and not the form)
Repeat Step 4 and 5 with ISpecifyPipelineComponentUI Interface Interface for our Component
Repeat Step 4 and 5 with IPipelineComponentDescription Interface Interface for our Component

Now we need to add details to IPipelineComponentUI Interface

After implementing all of the methods your component should look like the code below:

using System;
using System.Collections.Generic;
using System.Text;
using System.Runtime.InteropServices;
using Microsoft.CommerceServer.Interop;
using Microsoft.CommerceServer.Interop.Orders;
using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Runtime.Orders;

namespace CustomPipeline
{
    [ComVisible(true)]
    [GuidAttribute ("5904C354-F1B8-485c-89DD-883D26BCE85D")]
    public class Class1 : IPipelineComponent,
                        IPipelineComponentAdmin,
                        IPersistDictionary,
                        ISpecifyPipelineComponentUI,
                        IPipelineComponentDescription
    {
        // Status codes for pipeline components
        private const Int32 StatusSuccess = 1; // success
        private const Int32 StatusWarning = 2; // warning
        private const Int32 StatusError = 3;   // error

        // Sample Data
        string sampleData = null;
        bool isDirty = false;

        public Class1()
        {
            isDirty = false;
            this.InitNew();
        }

        #region IPipelineComponent Members

        public void EnableDesign(int fEnable) { }

        public int Execute(object pdispOrder, object pdispContext, int lFlags)
        {
            Int32 ReturnValue = StatusSuccess;
            IDictionary Context = (IDictionary)pdispContext;
            OrderContext myOrderContext = (OrderContext)Context["OrderContext"];
            return ReturnValue;
        }

        #endregion

        #region IPipelineComponentAdmin Members

        public object GetConfigData()
        {
            IDictionary Dictionary = new Dictionary();
            this.Save(Dictionary, Convert.ToInt32(false));
            return Dictionary;
        }

        public void SetConfigData(object pDict)
        {
            IDictionary Dictionary = (IDictionary)pDict;
            this.Load(Dictionary);
        }

        #endregion

        #region IPersistDictionary Members

        public string GetProgID()
        {
            return "CustomPipeline.Class1";
        }

        public void InitNew()
        {
            sampleData = "";
        }

        public int IsDirty()
        {
            return Convert.ToInt32(isDirty);
        }

        public void Load(object pdispDict)
        {
            IDictionary Dictionary = (IDictionary)pdispDict;
        //If the expected dictionary values do not exist use the defaults
        if (Dictionary["SampleData"] != null && Dictionary["SampleData"] != DBNull.Value)          sampleData = Convert.ToString(Dictionary["SampleData"]);
        }

        public void Save(object pdispDict, int fSameAsLoad)
        {
            IDictionary Dictionary = (IDictionary)pdispDict;
            Dictionary["SampleData"] = sampleData;
        }

        #endregion

        #region ISpecifyPipelineComponentUI Members

        public string GetPipelineComponentUIProgID()
        {
            return "CustomPipeline.Form1";
        }

        #endregion

        #region IPipelineComponentDescription Members

        public object ContextValuesRead()
        {
            object[] contextValuesRead = new object[0];
            return contextValuesRead;
        }

        public object ValuesRead()
        {
            object[] valuesRead = new object[0];
            return valuesRead;
        }

        public object ValuesWritten()
        {
            object[] valuesWritten = new object[0];
            return valuesWritten;
        }

        #endregion
    }
}

Compile the sample
Test the sample
Congratulations you have successfully implemented a UI to your component. Notice that when you save the value in the form and open the form it remembers the value.

Debugging your .NET Form in Pipeline Editor

I know I said that I would go over the Pipeline Debugging later on but this is the right place to go over how to debug your .NET Form inside the Pipeline Editor.

Launch the Pipeline Editor
From the File Menu select New
From the Choose a Pipeline Template select Empty.pct then select OK
Right click on Empty Pipeline Template and a new Stage
Right click on New Stage and insert your custom pipeline you just created
Launch Visual Studio 2005 and open your Custom Pipeline Project
From Visual Studio select the Debug menu then click Attach to Process...
From the Add to Process dialog find pipeeditor.exe process and attach to it
Put a break point in the ShowProperties method in your Form
Next from the Pipeline Editor right click on CustomPipeline.class1 component and select Properties...
From the Component Properties dialog navigate to Custom Properties tab and click Custom User Interface
Notice that the break point will be hit (if you had placed your break point before the show method of the form)
Now Continue and add a value to the text box
Close the form and save your pipeline
Open Pipeline Editor and navigate to your PCF file from step 14 and open it
Open your form and noticed that the value you had save previously is now displayed

A bit of explanation of the PCF file. The PCF file is a OLE Compound file which contain it's own file structure inside the file. The OLE Compound file has a root that is returned by OpenStorageFile method. The root may contain sub-storages or streams. I have a sample code on GotDotNET for Commerce Server called Pipeline Modifier. The methods used in the Pipeline Modifier is undocumented but if you search hard enough you can find information on it from Site Server. The Pipeline Modifier allows you to view the raw data of the PCF file and modified it on the fly. Since the Pipeline Editor does not allow you to use command lines to modify the PCF files I created this tool to help in the process of automating the daunting task of managing Pipelines manually. If you download this tool you will need to modify a few things. For example since Commerce Server 2007 has an interop for the Pipeline Interfaces you will need to reference this instead of PipeCompLib. Also you may encounter MDA warning which you can ignore. Now lets get back on track and learn about OrderForms.

OrderForms

An OrderForm represents a collection of items that a user placed in a shopping cart. Depending on how far the user has progressed through the purchasing process, an OrderForm might also contain the locations to ship the products to, the discounts that apply to the OrderGroup, and the ways that the user paid or will pay for the products.
There are two types of OrderForms a .NET OrderForm that is used during runtime and a COM OrderForm that is used in the Pipelines. The Commerce Server 2007 has good documentation of how to extend the Order System and there is even an example under the SDK folder OrdersExtensibility.

Orders Pipeline Adapters

So what happens when you create a .NET OrderForm then execute the basket Pipeline (or any other Pipeline)? Simply put the managed OrderForm is run through the Pipeline Adapter and mapped into COM OrderForm then the basket Pipeline is executed.

The Orders Pipeline Adapter marshals data between the managed-code object model and legacy Dictionary instances in your Orders System. The Pipeline Adapter uses mapping contained in an XML file to map data between the managed code object and the legacy object. Dictionary class instances are simply hierarchical name-value pair collections. Managed classes can be viewed the same way, with strongly-typed properties as the name-value pairing. A mapping between the two models is achieved with an XML format that specifies the managed classes and properties to map, and the target Dictionary and SimpleList layout for those instances in unmanaged code.

The default mapping file for the Orders System is called OrderPipelineMappings.xml. The default directory for OrderPipelineMappings.xml is %SystemDrive%\Inetpub\wwwroot\<ApplicationName>.

Summary

So you learned more about Pipeline Interfaces and should have an advanced understanding of them and how to use them as well as debugging the WinForm UIs created.

You also learned of the Pipeline Modifier tool to help you with automating the administration task of your PCF files.

You now know how the managed OrderForm is mapped to COM OrdrForm and for more reading on this I would suggest that you work with the sample OrdersExtensibility.

In the next on going post I will discuss how to debug your pipeline components as well as testing your components.

Everything you ever wanted to know about pipelines but were afraid to ask (Part II)

Max Akbar — Sat, 02 Sep 2006 22:48:00 GMT

In the previous post you learned some concepts of pipelines so by now you should have a good idea of what Pipelines are. In this part we are going to talk about creating\developing Pipeline components. Before doing this let cover some more basics.

Pipeline Editor

Pipeline Editor is a GUI tool that allows you to modify and create new pipeline files for more details see links bellow in the Commerce Server help documentation.

Pipeline Register (PipeReg.exe)

Commerce Server 2007 includes the Pipeline Component Registration Tool for efficient registration of creating custom pipeline components. Typically, registration would be done using the DllRegisterServer entry-point routine, as is done in C++.

The Pipeline Component Registration Tool simplifies the registration process for none C++ componenets by registering pipeline components for stage affinity and then exporting the data to a Registry Script (.reg) file so it can be deployed on other servers.

The PipeReg.exe tool is located under C:\Program Files\Microsoft Commerce Server 2007\Tools if you installed Commerce Server in its default location.

We will go over this tool more once we start developing pipeline components using .NET.

Commerce Server SDK and Pipelines

Under the Commerce Server SDK folder you will find three folders of interest when developing pipelines.

DumpOrder

A sample Microsoft Visual Basic script, DumpOrder.vbs, is supplied in the C:\Program Files\Microsoft Commerce Server 2007\Sdk\Samples\DumpOrder subdirectory if Commerce Server is installed in its default location. When it runs, the DumpOrder script writes the contents of the OrderForm object to a file. You use the DumpOrder script for debugging purposes.

To use the DumpOrder script

Add the Scriptor component to any stage in the pipeline. Double-click the Scriptor component icon. In the resulting property page, click the Scriptor tab, click VBScript in the Language drop-down list, and then click File.
In the File box, type the path to the DumpOrder.vbs script (or click Browse to find it).
The DumpOrder.vbs script takes a file name as a parameter, so type the full path name of the output file in the Config field. For example, filename=c:\order.log.
Click OK, and then save the pipeline configuration file.
Stop and restart Internet Information Services (IIS), or modify the web.config file to restart the application. The DumpOrder.vbs script will write a file with the name you specified as a parameter when the Order Processing pipeline runs.

Note: Make sure to give permissions to where the log file is generated to ASP.NET account or whatever account you use for the process. Also make sure to understand the security implications of giving write\modify to a directory or file.

MinMaxShipping

The Commerce Server SDK includes a complete pipeline component developed in C#. It is called MinMaxShipping, and can be found in the following folder:

C:\Program Files\Microsoft Commerce Server 2007\Sdk\Samples\MinMaxShipping if Commerce Server is installed in its default location.

Pipeline Registration Tool Source Code

Pipeline Registration Tool Source Code under C:\Program Files\Microsoft Commerce Server 2007\Sdk\Samples\Pipeline Registration Tool Source Code folder if Commerce Server is installed in default location and constitute the source files for Pipeline Register (PipeReg.exe) that helps you register pipeline components for stage affinity. It allows you to register the pipeline component on the computer on which the tool is being run, and it allows you to export the data to a registry script (.reg extension) for deployment to other servers.

A list of out of the box Commerce Server Pipeline Components

The following is a list of out of the box pipeline components that can be used to create custom pipeline files. Remember in the first part we went over some sample files that comes with Commerce Server and are to be used as references. Based on your business rules you can create your own custom pipelines.

Pipeline Component Name	Description
AddAttachments	Adds attachments to a direct mail message.
CheckInventory	Checks the inventory status for items in the customer's basket.
ComposeDMLMessage	Creates the body of a direct mail message.
CreateUPMCookie	Collects cookie data to pass to an Active Server Pages (ASP) page creating a personalized direct mail message.
CSFAdvertisingNeedOfDelivery	Makes sure that advertisements are selected often enough to meet business commitments.
CSFEvalTargetGroups	Used to target particular groups for advertising, content selection, and discounts. This component evaluates a list of expressions for each item in a list and adjusts item selection scores.
CSFFilterContent	Applies provided filters to a content list in a Content Selection pipeline (CSP).
CSFFormatTemplate	Merges data from selected items and their associated templates to form formatted strings. These are usually HTML strings ready for display on the page.
CSFHistoryPenalty	Applies penalties to content items based on how recently they have been selected.
CSFIISAppendToLog	Records information about content selection results in the QueryString field of the Internet Information Services (IIS) log file.
CSFInitPipeline	Used at the beginning of a Content Selection pipeline (CSP) to initialize the values needed in the rest of the pipeline.
CSFLoadAdvertisements	Loads advertising data for the Content Selection Framework through the CacheManager object.
CSFLoadDiscounts	Loads discount data for the Content Selection Framework through the CacheManager object.
CSFLoadHistory	Retrieves a history string from a user profile, an item in the ASP session collection, or a cookie.
CSFRecordEvent	Records event delta counts for the selected content items (the winners) in the Performance dictionary.
CSFRecordHistory	Records the identifiers of the winning content items in the history list string.
CSFSaveHistory	Records the history string in one of three locations: the User Profile object, the Active Server Pages (ASP) session collection, or the Hypertext Transfer Protocol (HTTP) cookie.
CSFScoreDiscounts	Adjusts scores of discount items to promote discounts most relevant to the current user.
CSFSelectWinners	Selects items based on their final scores in the Content Selection pipeline.
CSFWriteEvents	Used with the CacheManager object to log Content Selection Framework events.
DefaultHandlingCy	Used as placeholder handling components. They initialize the total handling for the order to zero (0).
DefaultItemPriceCy	Set the regular price of an item to the list price returned by pipeline components such as QueryCatalogInfo or QueryProdInfoADO.
DefaultOrderSubTotalCy	Calculates the subtotal for the order.
DefaultPayment	Assigns a default value to the payment authorization code. This component is usually replaced by a third-party payment component.
DefaultShippingCy	Placeholder shipping components. They set the shipping cost to zero (0).
DefaultTaxCy	Set the tax fields of the order to zero (0). These components are usually replaced by third-party tax components.
DefaultTotalCy	Calculates the order total from the subtotals.
OrderDiscount	Applies discounts to the shopping basket.
OrderLevelDiscountApply	Applies order-level subtotal discounts.
PaymentMethodRouter	Processes payments on an order.
POtoFile	Sends a purchase order or other textual data to a file.
QueryCatalogInfo	Retrieves catalog information for every item in the order form.
RecordPromoCodes	Records the promotion codes that have been applied to the order and adds promotional discounts to the list of discounts for the order form.
RedeemPromoCodes	Validates promotion codes and marks them as redeemed.
RequiredHandlingCy	Verifies that the handling total is present in the order.
RequiredItemAdjustPriceCy	Ensures that the current price for each item in the order is set and that it has not been changed since the last time the basket was viewed.
RequiredItemPriceCy	Verifies that each item in the order form has a regular price assigned to it.
RequiredOrderAdjustPriceCy	Adjusts the total cost of each item in the order after applying any discounts.
RequiredOrderCheck	Verifies that the order form contains at least one item.
RequiredOrderInitCy	Initializes the payment authorization code, order ID, totals, and subtotals in the order form.
RequiredOrderSubtotalCy	Ensures that a subtotal exists on the order form.
RequiredPayment	Verifies that the payment authorization code exists in the order form (is not NULL).
RequiredProdInfo	Deletes items flagged for deletion by a previous Product Info stage component.
RequiredShippingCy	Verifies that the shipping total has been set.
RequiredTaxCy	Verifies that the total tax and tax included appear in the order form.
RequiredTotalCy	Verifies that values on a page have not been tampered with or reset. The components compare values in the order against values in the _Verify_With dictionary.
ReservePromoCodes	Validates and reserves promotion codes.
Scriptor	Executes a script in a Microsoft ActiveX scripting language.
SendPrecomposedMessage	Sends a direct mail message composed in earlier stages in the pipeline.
SendSMTP	Sends an e-mail message to a specified recipient.
ShippingDiscountAdjust	Applies shipping discounts to the order.
ShippingMethodRouter	The ShippingMethodRouter pipeline component looks up and runs the pipeline components that calculate shipping costs for individual shipments, and then calculates the shipping total for the entire order.
Splitter	Divides the order into groups based on a list of item keys. Frequently used to divide the order into multiple shipments.
StepwiseShipping	Calculates shipping costs for shipments in the multiple-shipment shipping architecture. This component is never directly used in a pipeline; it is run by the ShippingMethodRouter pipeline component.
ThrottleDMLPerformance	Controls the speed with which direct mail messages are processed by the pipeline.
UpdateInventory	Checks the inventory status for an array of stock-keeping units (SKUs) and updates the SKU quantities in the Inventory System.
ValidateCCNumber	Checks the expiration date of a credit card and performs a checksum test on the number.
VerifyMessageBody	Checks the body of a direct mail message according to the user flags.
VerifyRecipientData	Checks the data about the recipient of a direct mail message.
XMLTracer	A troubleshooting and debugging tool that outputs the contents of the OrderForm object to a log file during any stage of pipeline execution.

Developing a custom Pipeline Component

Finally we can create pipeline components using Microsoft Visual C#, you can also create pipelines using Visual Basic 2005 and C++. So lets walk through a step by step guide for developing a custom pipeline component in this sample we will work with C#.

Start Visual Studio 2005.
On the File menu, click New, and then click Project. The New Project dialog box opens.
In the New Project dialog box, in the Project types pane, select the Windows child within the Visual C# branch of the tree, and then in the Templates pane, select the Class Library template.
In the New Project dialog box, choose an appropriate project name, location, and solution name, and then click OK. Your new class library project opens within Visual Studio 2005.
Open the Solution Explorer. Right-click your new project and then click Properties. The multi-tabbed project properties window opens in your workspace.
In the multi-tabbed project properties window, click the Build tab. Then, in the Output section, select the Register for COM interop checkbox. With this setting, Visual Studio 2005 will automatically register your pipeline component with COM.
In the multi-tabbed project properties window, click the Application tab. Then, in the Output section, select the Assembly Information button.

From the Assebly Information Dialog check Make assembly COM-Visable. Specifies whether types within the assembly will be accessible to COM. Corresponds to ComVisibleAttribute.
In Solution Explorer, right-click your project and then click Add Reference. The Add Reference dialog box opens.

In the Add Reference dialog box, on the .NET tab, scroll if necessary and select Microsoft Commerce Server Interop Assembly, and then click OK. Your project now includes a reference to Microsoft.CommerceServer.Interop.

Note

Many pipeline components will also need to reference the assemblies Microsoft Commerce Server .NET Application Framework and Microsoft Commerce Server Shared Types Assembly. Repeat steps 7 and 8 as required.

If you are passing Commerce Subsystem Context values or need to have access to .NET Commerce objects then you will use the Microsoft Commerce Server .NET Application Framework and Microsoft Commerce Server Shared Types Assembly to access Commerce resources. Microsoft Commerce Server Interop Assembly is required for the pipeline interfaces.

In Solution Explorer, right-click the file Class1.cs and then click Rename.
Type a more descriptive name for your C# source code file (make sure you retain the ".cs" file extension) and the press ENTER. When prompted about renaming all references to related code elements, click Yes. The name of your pipeline class will change as specified within your renamed C# source code file.
In your renamed C# source code file, add the following using directives below the default using directives:

using System.Runtime.InteropServices;
using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Interop;
using Microsoft.CommerceServer.Interop.Orders;

To add the appropriate attributes to your pipeline component class

In Visual Studio 2005, on the Tools menu, click Create GUID. The Create GUID dialog box opens.
In the Create GUID dialog box, choose the Registry Format, click Copy to create a GUID and copy it to the clipboard, and then click Exit to dismiss the tool.

Add the following two bolded lines immediately above your pipeline class declaration in your C# source code file, pasting the GUID created in step 2 from the clipboard.

Important

The GUID shown below and throughout this topic is an example. You must replace it with a unique GUID of your own.

[ComVisible(true)]

[GuidAttribute("D452305E-50C9-4031-BC94-6839BE6066EE")]
public class MyPipelineClass { }

To implement your pipeline class

Type the names of the interfaces from which you want your pipeline component to inherit. It must inherit the interface IPipelineComponent, and optionally it may inherit one or both of the interfaces IPipelineComponentAdmin and IPipelineComponentDescription. For this example we are only going to implement the IPipelineComponent.

[ComVisible(true)]
[GuidAttribute("D452305E-50C9-4031-BC94-6839BE6066EE")]
public class MyPipelineClass : IPipelineComponent { }

Your project should look something like bellow:

using System;
using System.Collections.Generic;
using System.Text;

using System.Runtime.InteropServices;
using Microsoft.CommerceServer.Interop;
using Microsoft.CommerceServer.Runtime;
using Microsoft.CommerceServer.Interop.Orders;

namespace CustomPipeline
{
    [ComVisible(true)]
    [GuidAttribute ("5904C354-F1B8-485c-89DD-883D26BCE85D")]
    public class Class1 : IPipelineComponent
    {
        // Status codes for pipeline components
        private const Int32 StatusSuccess = 1; // success
        private const Int32 StatusWarning = 2; // warning
        private const Int32 StatusError = 3; // error

#region IPipelineComponent Members
void IPipelineComponent.EnableDesign(int fEnable){}

        int IPipelineComponent.Execute(object pdispOrder, object pdispContext, int lFlags)
        {
            Int32 ReturnValue = StatusSuccess;
            // TODO: add code for the pipeline
            return ReturnValue;
        }
        #endregion
    }
}

Compile your project and after a successful build we will register your new pipeline component.

Register your Pipeline

You use PipeReg.exe tool to register your newly created pipeline component. We discussed the tool earlier also the source code for the tool is available under the SDK folder. PipeReg.exe can be located under c:\Program Files\Microsoft Commerce Server 2007\Tools\ if Commerce Server was installed in its default location.

Launch the PipeReg.exe EXE.
From the Pipeline Component Registration Wizard [Step 1 of 3] dialog Select Select component Type Library. Next specify the path by selecting the Path button with ellipses. When you compiled your pipeline component Visual Studio generated a Type Library file be sure to select that file then Select Next.
From the Pipeline Component Registration Wizard [Step 2 of 3] dialog Select All Stages from Available Categories List Box then Select the > Button. This will add our newly component to the All Stages category. Here you can also create your own custom stages.
From the Pipeline Component Registration Wizard [Step 2 of 3] dialog Select Register and export data. Make sure to note the location and name of the reg file. Then Select Next. Then Select Close after viewing the summary page.

Test your Pipeline

We will test our pipeline by loading it into a pcf file to make sure that the registration succeeded.

Launch the Pipeline Editor.
From the File menu Select New. Then from the Choose a Pipeline Template Select the OK button to choose the default template.
After the Pipeline Template has been loaded right click on any stage and then Select Insert Component.
From the Choose a Component dialog Select All from the Stages Drop Down. Then navigate until you find your component then Select OK.
Congratulations you have successfully created and tested your .NET pipeline component.

Making your component ready for production deployment

To deploy your new component Copy the assembly to the target computer and register the component using Regasm.exe. You must either deploy the component into the global assembly cache (GAC) by using Gacutil.exe or you may use Regasm.exe with the /codebase option to deploy your new pipeline component without putting it in the GAC. I would recommend your strongly sign your new component and add them into the GAC.

Summary

In this part your learned some more concepts on how to work with Pipeline Editor and Pipeline Registration when creating a custom pipeline component. You also walked through a step by step guide of creating a C# pipeline component and testing it to make sure it works.
In the next part of this ongoing post we will look deeper into the Interfaces of the pipeline components as well as way to debug your pipeline components. I will also show you how you can monitor the performance of your pipelines during execution.

Everything you ever wanted to know about pipelines but were afraid to ask (Part I)

Max Akbar — Fri, 18 Aug 2006 09:54:00 GMT

What are Pipelines

Commerce Server pipeline is a framework that links one or more components and executes them in sequence. The Pipeline framework provides stages to abstract one or more categories of work. The Pipeline Stage also determine the sequence in which each category of work is performed. Each Pipeline Component is COM object that is put inserted into a stage and is executed in sequence by the Pipeline Object. Pipelines are linked and it’s configuration stored in files Pipeline configuration files (.pcf).

Pipeline Execution

The following diagram displays the Basket Pipeline and the execution starts with the Product Info Stage and continues down to the last Stage Order Subtotal. You can add or delete Stages as well as move the sequence of a particular Stage.

Figure 1 Commerce Server Pipeline

Pipeline Properties

Use the Pipeline Properties dialog box to change the name of the pipeline, to specify its transaction compatibility, to specify its currency mode, or to save notes about the pipeline.

Figure 2 Pipeline Property

The following is a description of each property for the UI above.

Use this	To do this
Label	Type the name that the Pipeline Editor displays for the pipeline.
Transaction	Select which pipeline object that you can use the pipeline configuration file (.pcf) with. The valid options are as follows: · Any pipeline. You can use the configuration file together with an OrderPipeline object. · Requires transacted pipeline. You can use the configuration file together with transacted pipeline objects (PooledTxPipeline, MtsTxPipeline). · Requires non-transacted pipeline. You can use the configuration file together with non-transacted pipeline objects (PooledPipeline, MtsPipeline).
Supply a currency LCID	Specify a locale ID (LCID) for currency handling. A value of zero (0) indicates to use the default locale ID of the server. The default currency LCID is zero (0).
Supply the number of decimal places used for currency rounding	Specify how many digits of precision to use for the currency. For example, you use two decimal places for United States pennies. Commerce Server uses this value for rounding purposes, and to determine the scaling factor to use in legacy currency keys.
Description	Type descriptive comments about the pipeline.

Pipeline Stages

The following diagram displays the Product Info Stage which consists of three Pipeline components. You can add or delete components using the Pipeline Editor. You can also move the individual components sequence.

Figure 3 Product Info Stage

Stage Properties

Use the Stage Properties dialog box to change the properties assigned to a pipeline stage.

Figure 4 Stage Properties

The following is a description of each property for the UI above.

Use this	To do this
Label	Specify the name that the Pipeline Editor displays for the stage.
Description	Type descriptive comments about the stage.
GUID	View the GUID that identifies the component on any computer. This ID never changes.
Mode	A value of zero (0) prevents the stage from running.
Error level	Specify the error level for the stage.
Note	When any component in the stage generates an error above the level specified in the Error level box, the stage skips the remaining components in the stage, and logs the event in the log file. The pipeline maintains the maximum error level encountered by any component in the pipeline. It uses the Error Level setting on the stage to compare this maximum error level and only runs components in the stage if the current error level is less than or equal to the error level limit specified for the component.

Pipeline Component

A component is a Component Object Model (COM) object designed to perform some operation on a dictionary -- a collection of name/value pairs -- that is a different representation of a runtime object. This can be a dictionary that represents an OrderForm object or a dictionary that represents another type of object.

Figure 5 Query Catalog Info Pipeline Component

Components Properties

Use the Component Properties dialog box to change the name of a pipeline component, to view the class ID or Program ID of a component, and to save notes about a component. Use the Component Properties dialog box, Values Read and Written tab, to view the values that the component reads from and writes to the order form and the values it reads from the Context dictionary object. For descriptions of each value read and written, access the corresponding component from the Pipeline Component Reference. These two “Component Properties” and “Values Read and Written” are common to all Pipeline components.

Figure 6 Components Properties

The following is a description of each property for the UI above.

Use this	To do this
Label	Specify the name that the Pipeline Editor displays for the component.
Class ID	View the GUID that identifies the component on any computer. This ID never changes.
Program ID	View the easily recognizable ID for the component. This ID never changes.
Required	Check to make sure that the pipeline component is not removed from the pipeline.
Description	Type descriptive comments about the component.

Figure 7 Component Values Read and Written

The following is a description of each property for the UI above.

Note: The Pipeline Editor cannot display values read and written for components that do not support the IPipelineComponent Interface. We will discuss the Interfaces that the Pipeline components implement later on.

Use this	To do this
Values Read	View the values that the component reads from the order form before it performs its function.
Values Written	View the values that the component writes to the order form or other dictionaries after it completes its function.
Context Values Read	View the values that the component reads from the Context dictionary object. The Context dictionary object is passed as a parameter to the Execute method of the pipeline.

There are however some out of the box components that need additional configuration or other information, this data is displayed on additional property pages.

Properties Dialog Box Tab Name	Description
Eval Expressions Tab	Determines how the CSFEvalTargetGroups component evaluates targeting expressions for advertising, content selection, and discounts.
Execution Mode Tab	Determines how the PaymentMethodRouter component processes credit cards and whether to validate payment totals.
History Penalty Tab	Determines how the CSFHistoryPenalty component applies penalties to content items based on how recently they have been selected.
Load History Tab	Determines where the CSFLoadHistory component retrieves the history string.
Order Discount Tab	Determines how the OrderDiscount component applies discounts scheduled by the Marketing Manager to the shopping basket.
Order Level Discount Tab	Determines how the OrderLevelDiscountApply component applies order level subtotal discounts.
Payment Router Tab	Determine the behavior of the PaymentMethodRouter pipeline component when processing credit cards and validating payment totals.
PO to File Tab	Determines how the POtoFile component retrieves and sends a purchase order or other textual data to a file.
Record History Tab	Determines how many items the CSFRecordHistory component saves in the history list string, which is used to contain the identifiers of winning content items.
Save History Tab	Determines where the CSFSaveHistory component saves the history string.
Scriptor Tab	Stores the script to be run by the Scriptor component.
Select Winners Tab	Determines how the CSFSelectWinners component displays house ads.
Send SMTP Tab	Determines where the SendSMTP component sends an e-mail message and the information sent.
Splitter Tab	Determines how the Splitter component divides an order into groups based on a list of item keys.
Test SendSMTP Tab	Tests the configuration of the SendSMTP component by sending a test e-mail message.

Commerce Server provides five objects to execute pipelines:

1. MtsPipeline

Use this object to run a non-transacted Microsoft Commerce Server pipeline.

2. MtsTxPipeline

Use this object to run a transacted Microsoft Commerce Server pipeline configuration.

3. PooledPipeline

Use this object to run a Microsoft Commerce Server pipeline configuration file. The PooledPipeline object uses COM+ object pooling to greatly increase the loading speed of pipelines, where the contained pipeline components support object pooling.

4. PooledTxPipeline

Use this object to execute a Microsoft Commerce Server pipeline. Use in place of the PooledPipeline object where you need transactions. The PooledTxPipeline object uses COM+ object pooling to increase the loading speed of pipelines.

5. OrderPipeline

Use this object to run a Microsoft Commerce Server Content Selection pipeline. To create an Order Processing pipeline (OPP), use a PooledPipeline, PooledTxPipeline, MtxPipeline, or MtsTxPipeline object.

The MtsPipeline and MtxTxPipeline is recommended for development only. All other Pipelines are recommended for production. The reason for this is that the MtsPipeline and MtxTxPipeline objects do not load the configuration into memory and makes it easier to develop rather than stopping and starting IIS every time a change occurs.

Note: MicroPipe is no longer supported in Commerce Server 2007. In earlier version of the Commerce Server you could only execute the Pipeline component.

By default Commerce Server has the following Pipeline files:

1. Advertising.pcf

2. Basket.pcf

3. Chckout.pcf

4. Discounts.pcf

5. DMLPipe.pcf

6. Product.pcf

7. RecordEvent.pcf

8. Total.pcf

When unpacking the CSharp site you will also get the above Pipeline files. These Pipeline files can be used as template to start a new Commerce Site.

Note: Commerce Server 2007 does not have Pipeline templates.

Pipelines in a nutshell

So to summarize everything, Pipeline framework consists of COM objects that are linked and stored in pcf file format. You can further categorize pipelines into stages. Pipelines are executed by the Pipeline object and configured by Pipeline Editor. Pipelines can be executed transactional and be pooled for performance. Commerce Server has a dozen or more Pipeline components and several default pcf files containing one or more Pipeline components. You can also create your own Pipeline components.

How are Pipelines used in Commerce Server

Commerce Server has three types of Pipelines:

1. Order Processing

The Order Processing pipelines (OPP) are software infrastructures that link several components and run them in sequence on an OrderForm or Dictionary object. The Order processing Pipeline implement aspects of business-to-consumer and business-to-business checkout transactions such as discounts, Inventory checking, Product Catalog checking etc…

2. Content Selection Framework

The Content Selection Framework (CSF) is a platform-level framework for building targeted content delivery applications on the Internet. The targeted advertising and discount features of Microsoft Commerce Server are built by using the CSF. The framework provides the means for building new types of content delivery applications and makes it easy to customize and extend the advertising and discount delivery systems.

3. Direct Mailer

The Direct Mailer pipeline runs components that screen recipients and personalize e-mail, and then sends the personalized e-mail.

You can add third-party or custom components to the Commerce Server pipeline. Those components need implement only the standard pipeline component interfaces. They also, however, need to understand the dictionary keys that components in the pipeline use.

How Pipelines are executed

To execute a pipeline, you add the name of the pipe to the pipelines node for your site in the site Web.config file, see example bellow.

</pipelines>

Each pipeline node must have the following attributes:

· Name - The name that you will reference in your application when executing the pipeline.

· Path - The relative path of the pipeline configuration file (.pcf).

· Transacted - Set this attribute to true or false to indicate the pipeline’s transacted state.

· Type - You can use either OrderPipeline or CSFPipeline for this attribute. You use an OrderPipeline to process orders and a CSFPipeline to display advertisements.

· LoggingEnabled - Set to true to enable logging. When you enable logging, the log file is created in the pipelines\log directory. You must also set appropriate permissions for the current w3wp.exe process to be able to create log files.

Sample code to execute a pipeline.

PipelineInfo info1 = new PipelineInfo(pipelineName, OrderPipelineType.Basket)

Basket.RunPipeline(info1);

Pipeline Types available.

public enum OrderPipelineType

{

Custom,

Product,

Basket,

Total,

Checkout,

AcceptBasket

}

This enumerator provides pipeline type information to PipelineInfo to allow an object to tailor its behavior to the requirements of the particular pipeline in use, without relying on the name of the pipeline.

The AcceptBasket type is used by the LOB Adapter.

When using the Custom type, the PipelineInfo constructor will not attempt to set up the pipeline context.

Member name	Description
AcceptBasket	Indicates an AcceptBasket pipeline (e.g. AcceptBasket.pcf).
Basket	Indicates a Basket pipeline (e.g. Basket.pcf).
Checkout	Indicates a Checkout pipeline (e.g. Checkout.pcf).
Custom	Indicates a custom pipeline type.
Product	Indicates a Product pipeline (e.g. Product.pcf).
Total	Indicates a Total pipeline (e.g. Total.pcf).

Summary

At this point you should have a good context of what Pipelines are and in the next part we will get a deeper understanding of Pipelines by developing and understanding Pipeline internals. Keep an eye out for part II of the “Everything you ever wanted to know about pipelines but were afraid to ask”.