Error Handling in Pipelines

Error handling in a Commerce Server 2002 Web site revolves around the interaction of the Order Processing pipeline (OPP) with the OrderForm object, the pipeline objects (MtsPipeline, MtsTxPipeline, PooledPipeline, and PooledTxPipeline), and the MessageManager object.

The OrderForm object provides a detailed, in-memory summary of one or more shopping sessions, including merchant, user, and item information. You pass an initialized OrderForm object to the OPP by calling the Execute method of the pipeline object you are using.

As the OrderForm object goes through various stages of the OPP, the components in each stage read and write values to and from the OrderForm object.

For error processing, the critical members of the OrderForm object are its _Basket_Errors****and _Purchase_Errors collections. These collections store strings describing error conditions the OPP detects while processing other elements of the OrderForm object.

The _Basket_Errors collection is used to indicate inconsistencies in the order form data that should be noted whenever the basket is displayed. Basket errors are specific to items in the basket, and are used to make the customer aware of any such problem as soon as possible. One such error is that the price of a product as shown in the basket does not match the price as listed in the product database. This error might occur, for example, if the price has been changed between the time the customer put the item in the basket and the time the purchase has been completed.

The _Purchase_Errors collection applies to the order as a whole. This collection is used to indicate failures in the purchasing process, such as denial of a credit card. Purchase errors are those that would be discovered only when the customer attempts to make the purchase.

The OPP gets the error strings from the MessageManager object. The MessageManager object is the central repository of locale-based error messages for a site. Each message stored in the MessageManager object consists of a string that describes a given error condition, and a string identifier that uniquely identifies the message to the OPP. The MessageManager object creates the association between the string identifier and the string message through the AddMessage method that adds a message to the MessageManager object.

Although the string describing an error can vary from one site to the next, the string ID identifying a message does not change. For example, if the OPP is unable to validate a credit card in the OrderForm object, the pipeline attempts to retrieve the string associated with the message ID pur_bad_cc in the MessageManager object for the site. If the site developer has not associated a string with this message ID, a fatal error will cause the pipeline to stop. Otherwise, the OPP retrieves this message and writes it to the _Purchase_Errors collection in the OrderForm object. When the Execute method returns, you can examine this collection, and the strings in it can be used to provide site users with detailed descriptions of errors that occurred during order processing. For more information, see MessageManager Object.

Note

• Commerce Server pipeline components are not designed to retry after a failed attempt. When the pipeline stops processing, the pipeline process fails and the order is not processed.

See Also

Error Levels

Error Handling

Copyright © 2005 Microsoft Corporation.
All rights reserved.