In this tutorial, you will learn a few techniques that will allow you to query the Episerver Commerce catalogue. When you start working with Episerver Commerce, it is common to feel overwhelmed with the number of API's available to you. Finding the most appropriate API in order to perform the function you want can be a frustrating and time-consuming exercise at times. The Episerver SDK can definitely be lacking when it comes to Commerce. That is why the aim of today's guide is to cover these API's and explain what they do. After reading this guide, hopefully, you can decide which tool is best for your needs. Today, we will cover four APIs, these are:
IContentRepositorywhen you want to access your product data
ILinksRepositorywhen you want to play with the associations of objects within your catalogue
CatalogContextwhen you want to work with a lower level of abstraction within your catalogue
ReferenceConverterto get an Episerver reference based on a product code
If this sounds good to you, read on 🔥🔥🔥
When working with Episerver Commerce, you will frequently need to query the catalogue for product data. Common coding tasks range from creating a folder to create a product, getting data to display a product on your website, getting an item to add to a basket or associating a product with a category.
In Episerver, the items you will be working with will either be of type
NodeContent (more information about these types can be found here).
ProductContent represent products and
NodeContent represents folders. I'll ignore the other types for this article but it can be handy to know they exist.
IContentRepository or IContentLoader
If you have worked with Episerver CMS before, it is very likely that you will be familiar with the
IContentLoader API. Both of these APIs can be used to access Episerver Commerce content.
IContentLoader is a read-only API, while
IContentRepositoryallows you to perform tasks like
Save. Behind the scenes,
IContentRepository implements the
IContentLoader interface. This means anything you can do with
IContentLoader you can do with
IContentRepository. This is why I generally tend to favour using
IContentRepository. As your codebase grows and changes if you suddenly need to use the extra methods supplied with
IContentRepository you do not have to refactor any of your unit tests! Always using
IContentRepository makes life easier 🤔
You will be using
IContentRepository to get the data about your products and variants from Episerver (more information here and here.
IContentRepository is pretty easy to work with. it exposes methods like
ReferenceConverter is a very simple API, however, it is very useful when working with Episerver Commerce. In a lot of circumstances, you may only have your products SKU (Stock Keeping Unit)/product code. The reference converter takes in a code and returns a reference to the matching Episerver object:
One important thing to know about
ReferenceConverter is that it queries the database directly and does not work with a cache. Do not make unneeded database calls when you're rendering pages as it will impact performance!
CatalogContext allows you to work on a more database table layer. Using
CatalogContext you can access the
DataTable and all of Epsiervfer Comermces
DTO level catalogues. For example at this level, instead of working with an actual product, we have defined in the code, we work with content contained within a
Working at this level of abstraction gives you access to a few things that the
IContentRepository doesn't provide. Specifically, using
CatalogContext give you more controller over the relationships and associations between the objects. The
CatalogContext uses a singleton pattern and can not be used with dependency injection, yuk 🤢
The downside of using a singleton based API in your codebase is that it will be very hard to unit test your code. This is why if you have access to the newer versions of Episerver Commerce I would always recommend working with
IContentRepository and the
ILinksRepository. The code to get a product using
CatalogContext can be seen below:
To get a node/fodler, you can sue this code::
The links repository is one of the newer Episerver Commerce API's, available from version 7.5 onwards. The links repository is the place to look for handling catalogue relations and associations; for example, if you want to change the parent of a node, or, add an association (link) from a variant to a catalogue this is the API for you. As the repository works via an interface it's all unit-testable which is nice.
Now you know the APIs available to you. Go out and query to your little heart's content. Happy Coding 🤘