Service layer API
Every service layer API contains a number of abstract and generic methods for communicating with the ECS. Information flows in both directions. Product information, prices, and stock information need to be read from the ECS so that it can be presented to the visitor on the user interface. Shopping cart content, customer account information, and shipping information must be parsed over to the ECS so that an order can be created.
Default service layers can be customized or substituted.
Each method on the service layers accepts a single Request object and returns a single Result object. You can customize both the Request and Result objects individually for each method for maximum flexibility. The service layer interface remains the same, even when the domain model objects are customers, in addition to the parameters going in and the returned results.
If you have customized the Request or Result object for a method, then you can use the corresponding extension method, which accepts generics.
For example:
The default method signature for adding a line to a shopping cart:
public virtual CartResult AddCartLines([NotNull] AddCartLinesRequest request)The generic version of the same method:
public static TAddCartLinesResult AddCartLines<TAddCartLinesResult>([NotNull] this CartServiceProvider cartProvider, [NotNull] AddCartLinesRequest request)Service methods
If possible, use the following naming conventions for all methods on a service provider:
-
CreateEntityName (for example, CreateCart)
-
GetEntityName (for example, GetCart)
-
DeleteEntityName (for example, DeleteCart)
-
UpdateEntityName (for example, UpdateCart)
If possible, use the following naming conventions for all methods that manipulate related items on an entity:
-
AddRelatedEntityName (for example, AddLineItem)
-
RemoveRelatedEntityName (for example, RemoveLineItem)
-
UpdateRelatedEntityName (for example, UpdateLineItem)
Request parameters
A service method takes a single request object as a parameter and this request object must inherit from a ServiceProviderRequest. When you use a single request object instead of multiple parameters, the same service methods remain usable regardless of the customization. As service methods require additional data to function, simply extending the request object with new parameters exposes the newly required data to the presentation tier without having to modify the service method.
Customizing request objects
There are two options when extending a request object to handle more parameters. The first option is to simply extend the appropriate request class, similar to the following example:
public class CustomLoadCartRequest : LoadCartRequest
{
public CustomLoadCartRequest(string shopName, string cartId,
string userId, string customProperty)
:base(shopName, cartId, userId)
{
this.customProperty = customProperty;
}
public string customProperty { get; protected set; }
}In some cases, you will not be able to extend a request, instead, you can use the property bag on the request to pass down any properties you want:
request.Properties["customProperty"] = "customValue";Result objects
Result objects generally mirror request objects, with the difference that they inherit from ServiceProviderResult and have a collection for system messages. If possible, always return system messages instead of exceptions.
You can set messages on a result using the following pattern:
var message = (SystemMessage)this.entityFactory.Create("SystemMessage");
message.Message = “your custom error message goes here”;
args.Result.SystemMessages.Add(message);