This content is archived. See latest version here

Last updated: Oct 12 2015

This topic describes how to work with catalog content based on the IContent interface in Episerver.

Accessing catalog content as IContent

Episerver Commerce provides a content provider that can serve any catalog content as IContent. That means that you can use an IContentRepository to work with the content as you do in Episerver CMS.

public ContentReference CreateNewSku(ContentReference linkToParentNode)
    var contentRepository = ServiceLocator.Current.GetInstance<IContentRepository>();
    //Create a new instance of CatalogContentTypeSample that will be a child to the specified parentNode.
    var newSku = contentRepository.GetDefault<CatalogContentTypeSample>(linkToParentNode);
    //Set some required properties.
    newSku.Code = "MyNewCode";
    newSku.SeoUri = "NewSku.aspx";
    //Set the description
    newSku.Description = "This new SKU is great";
    //Publish the new content and return its ContentReference.
    return contentRepository.Save(newSku, SaveAction.Publish, AccessLevel.NoAccess);

For information about displaying Commerce content, see Using a CMS-style rendering template.

Content model

To get the full feature set, you need to connect a content type to the meta-class. Do that by creating a model class that inherits from the appropriate type in the EPiServer.Commerce.Catalog.ContentTypes namespace and decorating it with the CatalogContentTypeAttribute attribute.

using EPiServer.Commerce.Catalog.ContentTypes;
using EPiServer.Commerce.Catalog.DataAnnotations;
using EPiServer.Core;
using EPiServer.DataAnnotations;

namespace CodeSamples.EPiServer.Commerce.Catalog.Provider
    public class CatalogContentTypeSample : VariationContent
        public virtual string Description { get; set; }

        public virtual int Size { get; set; }

        [DecimalSettings(18, 0)]
        public virtual decimal Discount { get; set; }

The following types are available when you create Commerce models.

Type nameDescription
VariationContent A type for variant(variation)/SKU models.
ProductContent A type for product models.
BundleContent A type for bundle models.
PackageContent A type for package models.
NodeContent A type for category/node models.

You should not inherit from the following types because they exist only to show various states in the system:

Type nameDescription
CatalogContent A type for catalog models.
EntryContentBase A base type for VariationContent, ProductContent, BundleContent, PackageContent and DynamicPackageContent.
NodeContentBase A base type for NodeContent and CatalogContent.
RootContent The virtual root in Episerver's hierarchical representation of Commerce content.

Note: See Removal of MetaDataPlus tables in Breaking Changes in Commerce 9.

During the synchronization process, specific CLR types generate meta-fields of a specific MetaDataPlus type. You can modify the default mapping by using the BackingTypeAttribute, or creating the property manually in Commerce Manager before adding the code. The following table shows mappings for all supported types:

CLR TypeMetaDataPlus Type
Byte Integer (SmallInt, TinyInt and Int are also supported)
Int16 Integer (SmallInt, TinyInt and Int are also supported)
Int32 Integer (SmallInt, TinyInt and Int are also supported)
Int64 Integer (SmallInt, TinyInt and Int are also supported)
Double Float
Single Float
Float Float
Decimal Decimal
String LongString (ShortString and Text are also supported)
Boolean Boolean
DateTime DateTime (Date and SmallDateTime are also supported)
Url Url
XhtmlString LongHtmlString
ContentReference ShortString
PageReference ShortString

Commerce-specific attributes

Any attribute you can use in CMS can also be used in Commerce content type models. You can decorate your model with the following Commerce-specific attributes:

  • CatalogContentTypeAttribute

    If you want to connect the content type to an existing meta-class, use the CatalogContentTypeAttribute. Connect them by defining the name of the meta-class that should be connected to the content type.

    using EPiServer.Commerce.Catalog.ContentTypes;
    using EPiServer.Commerce.Catalog.DataAnnotations;
    namespace CodeSamples.EPiServer.Commerce.Catalog.Provider
        [CatalogContentType(MetaClassName = "WineSKU")]
        public class CatalogContentTypeAttributeSample : VariationContent
  • EncryptedAttribute

    Use this attribute to declare a property to enable Use Encryption. This encrypts the value when stored in MetaDataPlus.

  • UseInComparisonAttribute

    Use this attribute to declare a property to be used for comparison.

  • IncludeInDefaultSearchAttribute

    Use this attribute to declare a property to include the value in default search results. This will be used by the search provider system.

  • IncludeValuesInSearchResultsAttribute

    Use this attribute to declare a property to be included in search results. This will be used by the search provider system.

  • SortableInSearchResultsAttribute

    Use this attribute to declare a property to be flagged as index sortable. This will be used by the search provider system.

  • TokenizeAttribute

    Use this attribute to declare a property to be tokenized (word breaking).

  • DecimalSettingsAttribute

    Use this attribute to declare a property to have precision and scale.

Commerce-specific types

The types you can represent in MetaDataPlus are not directly mapped to a CLR type. Properties that are backed by meta-fields of these MetaDataPlus types need to be specified further than simply by the return type. The following table lists such MetaDataPlus types and additional requirements.

MetaDataPlus TypeCLR TypeAdditional Requirements
Dictionary [New in 7.7] string Decorated with [BackingType(typeof(PropertyDictionarySingle))]
Dictionary, multiline [New in 7.7] ItemCollection<string> Decorated with [BackingType(typeof(PropertyDictionaryMultiple))]

Limitations in synchronization

The synchronization of catalog models works the same way as with content types in CMS, except that the data is backed in MetaDataPlus. However, there are some limitations due to technical differences. The following are not done automatically, but instead require manual steps:

  • Change the type of a property. Will cause an exception.
  • Rename a model class. Unless specified by the CatalogContentTypeAttribute, a new meta class is  added, but the old one is left in the system.
  • Rename a property. Will add a new meta field, but the old one is left in the system.
  • Remove a property.

Different properties with the same name must have identical definitions. This means that you cannot have a property called "Description" on two different classes and make it culture specific on one, but not the other. This is because, in Meta Data Plus, meta fields are shared across meta classes. Hence, they can only have one definition. For more detailed information regarding the synchronization in CMS, refer to the Synchronization.

Do you have feedback on this documentation? Send an email to For development-related questions and discussions, refer to our Forums on