Orders System Task and Object Mapping from COM to the .NET Framework

Article
01/18/2011

The OrderForm and OrderGroup objects are the core of the Order System functionality in .NET Framework applications. This topic describes how objects and tasks in the COM-based version of Commerce Server map to equivalents in Commerce Server 2007.

Object Mapping

The following table describes how COM objects map to .NET equivalent for Commerce Server. The .NET Framework types in the following table are in the Microsoft.CommerceServer.Orders namespace unless otherwise noted.

COM	.NET Framework
OrderGroup	Basket, OrderTemplate, and PurchaseOrder classes, which are all derived from the OrderGroup abstract base class. OrderContext is a factory object for these types.
OrderForm OrderGroup.Value(OrderForms).Value(OrderFormName)	OrderForm
OrderForms Dictionary OrderGroup.Value(OrderForms)	OrderFormCollection
Item DictionaryOrderForm.Items(n)	LineItem
Items SimpleList OrderForm.Items	LineItemCollection
Address Dictionary	OrderAddress
Addresses Dictionary	OrderAddressCollection
OrderGroupManager	OrderManagementContext
MicroPipe	None. In .NET you can create and execute a pipeline component directly.
MtsPipeline PooledPipeline	OrderPipeline
Pipeline Context Dictionary	PipelineInfo

Task Mapping

The following sections contain common coding tasks and show you the COM and the .NET Framework approach to coding the solution.

Accessing the Root Object for Interacting with the Order System

COM	.NET Framework
Create an instance of the Commerce.OrderGroup object to obtain access to the Order System functionality.	CommerceContext.Current.OrderSystem (OrderContext class)

Loading a Basket or Creating a New Basket

In both the COM and the .NET Framework application object models, a new basket is created if one does not already exist for the user; otherwise, the existing basket is loaded.

In the COM object model, the userId parameter is a string usually representing a GUID. In the .NET Framework model, the userId parameter is a System.Guid structure.

COM	.NET Framework
OrderGroup.Initialize(connStr, userId) OrderGroup.LoadBasket	GetBasket

OrderGroup.Initialize(connStr, userId)

OrderGroup.LoadBasket

GetBasket

Saving a Basket

COM	.NET Framework
OrderGroup.SaveAsBasket	Save

Converting a Basket to a Purchase Order at Checkout

This task is typically done after the checkout pipeline has successfully run and occurs within the same transaction in which the pipeline was run.

COM	.NET Framework
OrderGroup.SaveAsOrder	`po = Basket.SaveAsOrder()` After it has been saved as an order, the object should not be accessed on the page. The returned object should be accessed instead.

COM

.NET Framework

OrderGroup.SaveAsOrder

po = Basket.SaveAsOrder()

After it has been saved as an order, the object should not be accessed on the page. The returned object should be accessed instead.

Searching for a Saved Purchase Order

COM	.NET Framework
Call the OrderGroupManager.SimpleFind method together with a SimpleFindSearchInfo object. Or call the Find method directly. Results are returned in an ADO Recordset object.	GetPurchaseOrdersForUser

Call the OrderGroupManager.SimpleFind method together with a SimpleFindSearchInfo object. Or call the Find method directly.

Results are returned in an ADO Recordset object.

GetPurchaseOrdersForUser

Loading an Existing Purchase Order

COM	.NET Framework
OrderGroup.Initialize(connStr, userId) OrderGroup.LoadOrder(orderId)	GetPurchaseOrder

OrderGroup.Initialize(connStr, userId)

OrderGroup.LoadOrder(orderId)

GetPurchaseOrder

Saving a Purchase Order

COM	.NET Framework
OrderGroup.SaveAsOrder	Save

Loading an Existing Order Template for a User

COM	.NET Framework
OrderGroup.Initialize(userId) OrderGroup.LoadTemplate(templateId)	GetOrderTemplate

OrderGroup.Initialize(userId)

OrderGroup.LoadTemplate(templateId)

GetOrderTemplate

Creating an Order Template as a Copy of an Existing Basket or Purchase Order

Order templates can be used for wish lists and saved shopping lists.

COM	.NET Framework
Load the existing basket or purchase order and then call the OrderGroup.SaveAsTemplate method. Or create a new OrderGroup object and use the AddOrderForm method to copy the order forms from the existing OrderGroup to the template. Then call the SaveAsTemplate method to save the new template. The AddOrderForm method replicates the order form. It does not add a new reference to the existing order form.	Create an OrderTemplate object and copy the order forms to the new template by using the Add method on the template. Save the new template by calling the Save method.

Load the existing basket or purchase order and then call the OrderGroup.SaveAsTemplate method.

Or create a new OrderGroup object and use the AddOrderForm method to copy the order forms from the existing OrderGroup to the template. Then call the SaveAsTemplate method to save the new template. The AddOrderForm method replicates the order form. It does not add a new reference to the existing order form.

Create an OrderTemplate object and copy the order forms to the new template by using the Add method on the template. Save the new template by calling the Save method.

Saving an Order Template

COM	.NET Framework
OrderGroup.SaveAsTemplate	Save

Running an Order Processing Pipeline on an OrderGroup

When a pipeline is run against an OrderGroup object, it is run against each order form in the pipeline, one at a time. If the pipeline is transactional, all pipeline executions occur in the context of a single transaction.

COM	.NET Framework
Create a pipeline context dictionary and set the key-value pairs needed by the components in the pipeline. Run the pipeline by calling the OrderGroup.RunPipe method. Note: To view an example, see the RunMtsPipeline method in the std_pipeline_lib.asp include file in the Solution Sites. The std_pipeline_lib.asp file is located in the <drive>:\Inetpub\wwwroot\<Solution Site>\include directory. This file is only available if the Retail or Supplier Solution Site has been unpacked.	Create an instance of the PipelineInfo object, passing the name of the pipeline. The PipelineInfo object is approximately equivalent to a COM pipeline context dictionary. The constructor takes special action for the well-known pipeline names Basket and Total. It automatically sets up many of the keys in the context dictionary that are required for the standard Commerce Server pipeline components. Custom keys can be set by accessing the Item property.

Create a pipeline context dictionary and set the key-value pairs needed by the components in the pipeline. Run the pipeline by calling the OrderGroup.RunPipe method.

Note:

To view an example, see the RunMtsPipeline method in the std_pipeline_lib.asp include file in the Solution Sites. The std_pipeline_lib.asp file is located in the <drive>:\Inetpub\wwwroot\<Solution Site>\include directory. This file is only available if the Retail or Supplier Solution Site has been unpacked.

Create an instance of the PipelineInfo object, passing the name of the pipeline. The PipelineInfo object is approximately equivalent to a COM pipeline context dictionary. The constructor takes special action for the well-known pipeline names Basket and Total. It automatically sets up many of the keys in the context dictionary that are required for the standard Commerce Server pipeline components. Custom keys can be set by accessing the Item property.

Retrieving a List of Configured Shipping Methods

COM	.NET Framework
ShippingMethodManager.GetInstalledMethodList The COM version of ShippingMethodManager.GetInstalledMethodList takes three arguments: a filter criterion, a sort order, and an array of columns to return.	GetShippingMethods The .NET Framework version of OrderContext.GetShippingMethods takes one argument: the language. This method returns all enabled shipping methods in that language.

Accessing the Collection of OrderForms Objects in an OrderGroup

COM	.NET Framework
OrderGroup.Value(OrderForms) This is a Commerce.Dictionary object that contains the OrderForm objects keyed by name (the default is the name of the default OrderForm object).	OrderForms

OrderGroup.Value(OrderForms)

This is a Commerce.Dictionary object that contains the OrderForm objects keyed by name (the default is the name of the default OrderForm object).

OrderForms

Adding a New Line Item to an OrderForm Object

COM	.NET Framework
Create a Commerce.Dictionary object that represents the item. Typically, the dictionary contains at least the following keys: quantity product_catalog product_id product_variant_id (for variants) Then call the OrderGroup.AddItem(dictItem) method.	Create an instance of the LineItem object, passing properties of the product to the constructor as arguments. Set any additional custom properties by using the Item property of the LineItem object. Add the LineItem object to the OrderForm object by using the Add method.

Create a Commerce.Dictionary object that represents the item. Typically, the dictionary contains at least the following keys:

quantity
product_catalog
product_id
product_variant_id (for variants)

Then call the OrderGroup.AddItem(dictItem) method.

Create an instance of the LineItem object, passing properties of the product to the constructor as arguments. Set any additional custom properties by using the Item property of the LineItem object. Add the LineItem object to the OrderForm object by using the Add method.

Share via