API Changes Made to the Orders System
The Microsoft.CommerceServer.Runtime.Orders namespace has undergone major changes in Commerce Server 2007. Plus, an additional namespace, Microsoft.CommerceServer.Orders has been added for additional functionality.
The following list contains information about new classes and members that have been added to the Microsoft.CommerceServer.Runtime.Orders namespace.
The GetXml method, of the OrderGroup class, is a new method that adds support for converting an order to an XML format.
The Payments collection, of type PaymentCollection, is a new collection that adds the ability for an order to contain multiple payment types to account for partial credit card and partial gift certificate payment types. The base abstract Payment class has several derived classes in the Orders System. These include the CreditCardPayment, CashCardPayment, GiftCertificatePayment, and PurchaseOrderPayment classes. Each of these payment types is stored in its own table by the PurchaseOrder class mapped storage, so that they can be individually data mined.
Instances of the Basket class can now be named so that multiple baskets can be created per user.
The OrderForm class now has several new collections, PromoCodes and PromoCodeRecords, along with other new properties that directly support the promotion code and discounting capabilities of the Marketing System. Instances of the PromoCodeRecord class are mapped to their own table by the PurchaseOrder class mapped storage, so that they can be data mined by using SQL queries.
The LineItem class has two new collections, OrderLevelDiscountsApplied and ItemLevelDiscountsApplied, along with other new properties that directly support the discounting functionality in the Marketing System. Instances of the DiscountApplicationRecord class are mapped to their own table by the PurchaseOrder class mapped storage, so that they can be data mined by using SQL queries.
Two new classes, Shipment and ShipmentCollection, in addition to the Shipments property on the OrderForm class have been added to Commerce Server 2007. The Shipments property implements a weakly-typed property indexer for run-time extensibility and backward compatibility with dictionary-based shipment keys used in Commerce Server 2002. It also has a collection, ShippingDiscounts, along with other properties that directly support the Commerce Server discounting system. DiscountApplicationRecord instances are mapped to their own table by PurchaseOrder mapped storage. This means that they can be data mined by using SQL queries.
The OrderContext class adds the ability to perform generalized user-defined SQL search queries by using stored procedures that can return a collection of OrderGroup class instances in an OrderGroupCollection class. Default search implementations are provided out of the box.
The following list describes the mapping between deprecated Commerce Server 2002 orders classes and new or updated orders classes that are provided in Commerce Server 2007.
Most Commerce Server 2007 orders classes implement the IEnumerable interface just as Commerce Server 2002 classes did. However, the enumerator over a Commerce Server 2007 class returns only the weakly-typed properties of that class, whereas the Commerce Server 2002 enumerator returned each of the Dictionary key-value pairs that represented the class instance.
Commerce Server 2007 orders data classes derived from MappedStorageBase to support mapped storage. This base class was not present in Commerce Server 2002.
Commerce Server 2007 classes derive from the ISerializable interface to support Basket class and OrderTemplate class binary serialization. Each class implements the getobjectdata method of the ISerializable interface and a deserialization constructor.
Unlike Commerce Server 2002, most classes in Commerce Server 2007 do not implement the IDisposable interface. The unmanaged resources used in Commerce Server 2002 have been mostly eliminated in Commerce Server 2007.
Orders classes throw more meaningful exceptions in Commerce Server 2007. The orders exception hierarchy derives from the CommerceOrderSystemException class that has been made an abstract base class in Commerce Server 2007 with specific error conditions that correspond to specific exception types. These more meaningful exceptions make site debugging and handling specific exceptions easier when you use the orders classes that are provided in Commerce Server 2007. Strongly typed string properties are limited to as many characters as are available in the column to which the property is mapped by using mapped storage. String property setters throw an ArgumentException when the string being set is too long and would be truncated. In Commerce Server 2002, implicit truncation was allowed.
Commerce Server 2007 orders classes prevent bypassing strongly typed properties using weakly-typed key names. For example, when you use an instance of the LineItem class, you cannot set the strongly typed property ProductCategory by using the weakly-typed property indexer to set the key “product_category”, this will throw a PropertyConflictException in Commerce Server 2007.
There are many new web.config keys specific to the Orders System in Commerce Server 2007.
The following list describes the changes that were made to the OrderGroup class:
OrderGroup.Xml has been removed. Use GetXml instead.
OrderGroup.TaxIncluded has been removed.
The following list describes the changes that were made to the Basket class:
The UserID property of the Basket class has been moved to the OrderGroup base class as SoldToId because it was previously implemented in more than one OrderGroup subclass. The BasketID property now points to SoldToId instead of returning the UserID from the Basket class.
The SetPropertyOnOrderForms was a member of the Basket class method in Commerce Server 2002. It is now a member of the OrderGroup class.
The following list describes the changes that were made to the OrderTemplate class:
The UserID property on the OrderTemplate class has been moved to the OrderGroup base class as the SoldToId property, because it was previously implemented in more than one OrderGroup subclass.
OrderTemplate now implements the ConvertToBasket method that returns a Basket populated from the contents of the order template instance. This basket can be used instead of calling Add.
The following list describes the changes that were made to the PurchaseOrder class:
- Removed the PurchaseOrderID property. Use OrderGroupId instead.
The following list describes the changes that were made to the OrderForm class:
OrderForm(IOrderForm) has been removed, because support for the IOrderForm COM object has been removed in Commerce Server 2007.
The Dictionary property of the OrderForm class has been removed, because Orders classes are no longer based on COM Dictionary instances.
TaxIncluded has been removed as part of removal of sample tax components that were previously included with Commerce Server.
The following list describes the changes that were made to the LineItem class:
The Quantity property is now a System.Decimal value instead of an integer. However, only whole numbers are supported. If a quantity property is set with a fractional value an InvalidOperationException will result.
LineItem now implements strongly typed properties to replace various legacy keys. The PlacedPrice property replaces the key cy_placed_price, the ListPrice property replaces _cy_iadjust_regularprice, and the ExtendedPrice property replaces _cy_oadjust_adjustedprice.
The ShippingAddressId property replaces ShippingAddress in the Commerce Server 2002 classes.
The following list describes the changes that were made to the OrderAddress class.
The OrderAddressId property replaces the ID property in the Commerce Server 2002 classes.
The TelephoneNumber property in Commerce Server 2002 is superseded in Commerce Server 2007 by the DaytimePhoneNumber, EveningPhoneNumber, and FaxNumber properties.
The ShippingAddressID property has been removed.
Commerce Server 2007 adds the new Email and Organization properties for tracking more user information related to an order.
The following list describes the changes that were made to the PipelineInfo class:
PipelineInfo has a new constructor, PipelineInfo Constructor (string, OrderPipelineType), that should be used instead of the PipelineInfo(string) constructor to provide the Orders System with information about the intended use of the PipelineInfo class.
PipelineInfo now implements IDisposable. This means you should now call the Dispose method on all PipelineInfo instances you create to make sure that resources are released in a timely manner.
OrderGroupSearch and OrderGroupSearchOptions have been removed in Commerce Server 2007. The new search functionality in Commerce Server 2007, in the runtime, and the data management object model, for the Orders system, supersedes these classes.