This topic provides general guidelines and recommendations for implementing Episerver Commerce solutions, and modifying the back-end Commerce Manager system. The recommendations are based on common scenarios and input from implementation projects.
The purpose of these guidelines is to ensure stability and the best possible performance for your Commerce implementation. Most projects, especially first-time projects done by development teams with limited Commerce experience, are better off following proven recommendations to avoid mistakes, technical debt, as well as performance and scalability issues.
Before making any exceptions from implementation recommendations, ensure that you have a solid understanding of the underlying framework. Deviating from the recommended way of doing things may create more work than necessary, and make future upgrades more difficult. See the Episerver Commerce Developer Guide to learn more about the Commerce framework.
Plan project carefully
Commerce projects often take more time than originally estimated due to the complexity of areas like pricing, external integrations, and shipping and payment providers. Allow enough time for planning and design, and start small. Especially for first-time complex projects, it is recommended to do a proof-of-concept first, with a complete order process in place.
Document code changes
When altering workflows or other downloadable code that is added to your solution, make it a habit to clearly comment and document the code in the project. Well-documented code maintained in separated modules makes future system upgrades much easier.
Spend time on catalog design
Start early with the catalog modeling, since this can be complex and often requires more design than originally realized. Let the website catalog hierarchy guide your catalog structure, and limit the number of variants/SKUs associated with each product to avoid performance implications.
See Guidelines for working with catalogs for information about catalog modeling.
Use the search API
The built-in search API is useful especially for category landing pages and large catalog structures. It ensures better website performance, offloads database search and retrieval procedures, and provides paging and facets functionality. See Search.
Set search options correctly
The metafield/model field search options are often misunderstood and misused. Two typical examples are:
- Tokenize. This is often overused even for fields that do not need to be searchable.
- IncludeValuesInSearchResults. Overuse of this adds unnecessary bulk to the search index.
See Catalog meta classes and fields in the Episerver User Guide for a description of the search properties for catalog meta-classes and fields.
Turn on catalog caching
You should have a clear strategy for caching. Either turn catalog caching on, or implement your own solution. Consider this especially for pricing, and warehouse and inventory updates. See Caching.
Understand StoreHelper and CartHelper
Store helpers are useful, but you need to understand how they work before using them. Most helper classes can be downloaded from Episerver World (requires login). These can be modified to suit your needs, for instance by adding caching and other logic. As an example, the StoreHelper has no caching for prices, so this needs to be added.
Other limitations to helper implementations are, for instance, that CartHelper does not allow a variant/SKU to be added multiple times as multiple line items. Regarding ownership of business logic, for StoreHelper use the ReadOnlyPricingLoader instead. For CartHelper, download the code and make it "your own."
Use the payment and shipment provider models
When implementing payment processing and shipping rate calculation, use the provider model. This makes them usable in Commerce Manager, and includes storage for configuration settings. See Payments and Shipping.
Avoid database modifications
Modifying the database includes editing or deleting database tables and stored procedures. This can break functionality and prevent future upgrades.
Minimize use of MetaImage
The MetaImage metafield is used for storing images. If you use this metafield type in catalog meta-classes, it works for smaller, low-traffic websites, but is inefficient for larger websites as the output is stored in the database. Also, it is not accessible outside of an entry. However, the MetaImage meta-field performance was improved recently.
Avoid using Session
Episerver CMS does not require sessions. Commerce Manager makes use of session and viewstate, and requires sticky session to operate. The Episerver Commerce sample site uses session only to store discount coupon information, but this can be implemented without session. If you do not use session, you do not need to implement sticky sessions on web farms, which eliminates unnecessary overhead.
Keep Commerce Manager non-public
Modifying Commerce Manager
You can modify Commerce Manager to create a customized administration interface. However, this may require more work when upgrading the solution. It is often easier to create the administration pages for Commerce in Episerver CMS instead. Consider the points listed below if you decide to modify Commerce Manager for your solution.
Store configuration files, web controls, or web pages in a structure that reflects where the files belong in the Commerce Manager file structure. This makes deployment intuitive, and minimizes the project, making it more manageable.
A common choice is to name the web control/web page files differently to distinguish them from the source files. The advantages to changing file names are:
- original and modified files can co-exist for easy comparison
- an upgrade does not overwrite the modified files
A disadvantage is that you need to modify config files so that they point to the new files.
Document and separate
Follow these steps to make future upgrades easier.
- When you make modifications, clearly comment the nature of and reasons for the change.
- If possible, separate the logic modification in a different method or, better yet, a separate class or even library.
- Keep a separate web project that contains only the modified files.
- Modify the namespace of your custom controls to be unique to the separate project.
Last updated: Jul 10, 2014