Commerce Foundation Presentation

Microsoft Multi-Channel Commerce Foundation exposes a single service having a single CommerceProcessRequest method. As input a Request is specified while the response is always of type CommerceResponse.

Method	Description
ProcessRequest	The CommerceRequest input parameter must contain at one or more Commerce Server 2009 operation requests. Commerce Server 2009 returns a CommerceResponse result. When the CommerceRequest contains multiple operations, the CommerceResponse contains multiple operation responses in the corresponding order.

OperationServiceAgent

The OperationServiceAgent provides the interface that a presentation application uses to execute Microsoft Multi-Channel Commerce Foundation requests.

An implementation using the service agent should only create a single instance of this class. This will ensure that when Commerce Server 2009 it is configured to use Windows Communication Foundation (WCF), only a single WCF channel is created.

Internally, the ServiceLocator<> is the key to determine if the service will be used as an In-Process library call or a WCF enabled service. This is fully specified in Commerce Server 2009 configuration parameters.

Note: While WCF is not supported in this release, it has not been disabled.

CommerceRequest

A CommerceRequest quest specifies the CommerceRequestContext along with at least one operation to perform. Microsoft Multi-Channel Commerce Foundation supports multiple operations in a single request to optimize application performance. For example, when browsing a product catalog a single page may contain a list of products within a product category as well as the marketing information relevant to the displayed products.

Property	Description
RequestContext	Provides contextual information from the caller to Microsoft Multi-Channel Commerce Foundation. Details are described later.
Operations	Provides a list of 1 or more operations to be processed by Microsoft Multi-Channel Commerce Foundation. Operation responses are always returned in the same order as they were specified in the request. Details on each of the supported operations are provided later in this document.

CommerceRequestContext Class

Each request requires a CommerceRequestContext. The request context object must be provided for every Commerce Server 2009 request, and is never updated by Commerce Server 2009.

Property	Data Type	Description
Channel	String	The Channel property indicates the sales channel (retail brand and device), and selects Microsoft Multi-Channel Commerce Foundation processing options such as specific operation handlers, and the relevant Commerce Server site. The channel is exposed in Commerce Server Marketing subsystem so specific marketing advertisements can be targeted for specific channels if required. Microsoft Multi-Channel Commerce Foundation has a Channel expression targeting context that can be used when evaluating which ads, discounts can be applied. This allows marketers to target ads and discounts to specific sales channels.
RequestId	String	Unique identifier of the request which is propagated throughout the current request and used by the Microsoft Multi-Channel Commerce Foundation tracing facility. For a web UI this should be the current http request id.
UserId	String	User id of the current user. The association between the SessionToken and UserId is validated for every API call.
UserLocale	String	The UserLocale property uses the CultureInfo property to format data (such as dates and times, and large numbers) associated with this data. This is separated from UserUILocale (see below) because in a specific solution the available languages for the data may be different than the available languages of the user interface. A calling application could use the GetThreadLocale function or the System.Threading.CurrentCulture .NET API to get the calling thread locale.
UserUILocale	String	The UserUILocale property uses the CultureInfo property to format locale-specific UI messages such as errors, including data formatting (such as dates and times, and large numbers) associated with these messages. A calling application could use the GetUserDefaultUILanguage function or the System.Threading.CurrentUICulture .NET API to get the current user UI language.

CommerceResponse

Each request to Commerce Server 2009 creates a CommerceResponse.

The following table lists the properties of the CommerceResponse class.

Property	Data Type	Description
OperationResponses	List<CommerceOperationResponse>	Contains the details of a specific operation response. When the system sends multiple operations as part of a single request, the operation responses of the CommerceOperationResponses collections are returned in the same order as they were specified in the request.

Request Builder Classes

Commerce Server 2009 includes generic request builder helper classes that help you construct operation requests. A request builder exists for each type of Microsoft Multi-Channel Commerce Foundation operation.

CommerceBaseBuilder

Every request builder derives from the CommerceBaseBuilder<> generic class.

The ToOperation() public abstract method returns the Microsoft Multi-Channel Commerce Foundation operation objects. The ToRequest() contains a fully constructed Microsoft Multi-Channel Commerce Foundation request. Internally the builders call ToOperation() when building the request.

CommerceMultiOperation

The CommerceMultiOperation class provides an easy way to construct a Microsoft Multi-Channel Commerce Foundation request that contains multiple operations. This can optimize 3-tier performance by reducing the per-request processing overhead for some typical application scenarios.

Method	Description
ToRequest()	Method returns a properly constructed multi-operation request.

Error Reporting

Microsoft Multi-Channel Commerce Foundation uses exceptions to communicate error conditions to the calling process. These manifest themselves in the form of FaultException exceptions. Every exception thrown by the service is wrapped, even system exceptions. This ensures the integrity of the open channel socket by ensuring it is not abruptly closed by the Windows Communication Foundation.

FaultException contains application specific fault details in the member FaultException.Detail. The Microsoft Multi-Channel Commerce Foundation uses specific fault details to communicate errors that occurred during the processing of the request. GeneratOperationFault is the base class for all fault details returned by Microsoft Multi-Channel Commerce Foundation.

Property	Description
Message	Error message.

There are several specialized implementations of the GeneralOperationFault:

Implementation	Description
AuthorizationFault	Reserved for future use.
ItemAlreadyExistsFault	This fault can be thrown if you are attempting to create an item that already exists.
ItemDoesNotExistFault	This fault can be thrown if you are attempting to perform an operation on an item that does not exist.
InvalidSearchQueryFault	This fault can be thrown during a SharePoint search if the search criteria entered was not supported. InvalidSearchQueryFault supports two SearchErrorTypes MalformedQuery and AllNoiseQuery.
ValidationFault	This fault can be thrown by the operations mapping to Commerce Server profile objects. ValidationError is exposed through ValidationFault.ValidationErrors. This member contains a list of all of the validation errors that were generated while processing the operation.

See Also

Other Resources

Commerce Foundation Objects and Models

Commerce Foundation CommerceEntity

Developing with the Multi-Channel Commerce Foundation

Commerce Foundation Operations