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:

  • Use IContentRepository when you want to access your product data
  • Use ILinksRepository when you want to play with the associations of objects within your catalogue
  • Use CatalogContext when you want to work with a lower level of abstraction within your catalogue
  • Use ReferenceConverter to get an Episerver reference based on a product code

If this sounds good to you, read on 🔥🔥🔥

The Catalog

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 VariationContent, ProductContent, BundleContent, PackageContent or NodeContent (more information about these types can be found here).

VariationContent and 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 IContentRepository or 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 Delete and 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 Load and Save methods.

Reference Converter

The 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

The 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 CatalogEntryDto entity.

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::

ILinksRepository

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 🤘