The old package Geta.EPi.Extensions has been renamed to Geta.Optimizely.Extensions. Install it using Nuget package manager or from the command line:

Install-Package Geta.Optimizely.Extensions

The package has almost the same functionality as the previous version. The only change is that we have removed XForms related functionality as it is not supported in Optimizely 12 anymore.

For more information check the Github page.

Sitemaps and Sitemaps.Commerce

The old packages Geta.SEO.Sitemaps and Geta.SEO.Sitemaps.Commerce has been renamed to Geta.Optimizely.Sitemaps and Geta.Optimizely.Sitemaps.Commerce. Install those using Nuget package manager or from the command line:

Install-Package Geta.Optimizely.Sitemaps
Install-Package Geta.Optimizely.Sitemaps.Commerce

After installation, you have to configure it. Register the Sitemaps and/or Sitemaps Commerce in the service collection first:

services.AddSitemaps(x =>
{
  x.EnableLanguageDropDownInAdmin = false;
  x.EnableRealtimeCaching = true;
  x.EnableRealtimeSitemap = false;
});
services.AddSitemapsCommerce();

Then make sure that you have razor pages mapped:

app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
});

After that, you will see a new top menu item for the Sitemaps in the Optimizely administration UI. There is a new administration user interface, but it has the same functionality as the old one.

For more information check the Github page.

Geta.Optimizely.GoogleProductFeed

The package Geta.GoogleProductFeed has been renamed to Geta.Optimizely.GoogleProductFeed so that all the naming is consistent with other Optimizely packages. Install it using Nuget package manager or from the command line:

Install-Package Geta.Optimizely.GoogleProductFeed

After installation, you have to configure it. Register the GoogleProductFeed in the service collection first:

services.AddGoogleProductFeed(x =>
{
    x.ConnectionString = _configuration.GetConnectionString("EPiServerDB");
});

Then you have to create your FeedBuilder. See the documentation.

Once, it is created register it in the service collection:

services.AddTransient<FeedBuilder, MyFeedBuilder>();

For more information check the Github page.

Geta.Optimizely.ContentTypeIcons

We had a package Geta.Epi.FontThumbnail for the older Episerver/Optimizely versions. The package name did not describe what it was. So we renamed it to Geta.Optimizely.ContentTypeIcons. Install it using Nuget package manager or from the command line:

Install-Package Geta.Optimizely.ContentTypeIcons

After installation, you have to configure it. Register the ContentTypeIcons in the service collection first:

services.AddContentTypeIcons(x =>
{
    x.EnableTreeIcons = true;
    x.ForegroundColor = "#ffffff";
    x.BackgroundColor = "#02423F";
    x.FontSize = 40;
    x.CachePath = "[appDataPath]\\thumb_cache\\";
    x.CustomFontPath = "[appDataPath]\\fonts\\";
});

Now you can start using it by adding the ContentTypeIcon attribute to your content types. For example:

[ContentTypeIcon(FontAwesome5Brands.Github)]

This attribute on a page type will show you a Github icon when you will create a new page of this page type. Also, if you have the EnableTreeIcons setting enabled, you will see the icon in the content tree.

You can also use the TreeIcon attribute to override the behavior for the content tree. You can set a different icon or ignore the icon completely:

[TreeIcon(Ignore = true)]
[TreeIcon(FontAwesome5Solid.CheckDouble)]

For more information check the Github page.

We have changed the name of the package again. The reason for this is that the old name was inconsistent throughout the code. The assembly name was Geta.404Handler, but namespaces started with Geta.NotFoundHandler. We could have changed namespaces to have 404Handler in the name, but namespaces' parts in .NET can't start with a number.

ASP.NET 5 and Optimizely

After reviewing the library, we found that it was not so dependent on Optimizely (Episerver). So we refactored the library that supports ASP.NET 5 and added administrative UI integration in Optimizely. Now there are three separate packages:

• Geta.NotFoundHandler - the core library for ASP.NET 5.
• Geta.NotFoundHandler.Admin - the administrative UI.
• Geta.NotFoundHandler.Optimizely - a module that integrates administrative UI in Optimizely UI.

Getting started in ASP.NET

In an ASP.NET 5 project install Geta.NotFoundHandler.Admin and in the Startup.ConfigureServices method configure the NotFoundHandler. You have to provide a connection string at least.

public void ConfigureServices(IServiceCollection services)
{
    var connectionString = ... // Retrieve connection string here
    services.AddNotFoundHandler(o =>
    {
        o.UseSqlServer(connectionstring);
    });
}

By default, users in the Administrators role will have access to the administration UI. You can change the default policy in the configuration:

public void ConfigureServices(IServiceCollection services)
{
    var connectionString = ... // Retrieve connection string here
    services.AddNotFoundHandler(o =>
    {
        o.UseSqlServer(connectionstring);
    }, policy =>
    {
        policy.RequireRole("MyRole");
    });
}

Next, initialize NotFoundHandler in the Configure method as the first registration. It will make sure that the handler will catch all 404 errors.

public void Configure(IApplicationBuilder app)
{
    app.UseNotFoundHandler();
}

Now you should be able to access administrative UI by https://mysite/Geta.NotFoundHandler.Admin.

Getting started in Optimizely

In an Optimizely project install Geta.NotFoundHandler.Optimizely package. Then configure the handler in Startup.ConfigureServices method. Set the connection string and add access for the CMS administrators.

public void ConfigureServices(IServiceCollection services)
{
    var connectionString = ... // Retrieve connection string here
    services.AddNotFoundHandler(o =>
    {
        o.UseSqlServer(connectionString);
    }, policy =>
    {
        policy.RequireRole(Roles.CmsAdmins);
    });
    services.AddOptimizelyNotFoundHandler();
}

As in the ASP.NET case, initialize NotFoundHandler in the Configure method as the first registration.

public void Configure(IApplicationBuilder app)
{
    app.UseNotFoundHandler();
}

Run the application and in the Optimizely administrative UI you will find a link to the NotFounHandler administrative UI in the top menu.

Summary

NotFoundHandler now is ready for use in the new Optimizely 12, but if you are using older versions of Optimizely/Episerver, then we will still support those as Geta.404Handler.

The source code and documentation for the new NotFoundHandler is available on GitHub.

If we look at the single responsibility principle, a start page with settings is doing too much. It has start page related content and also site-wide settings. When you have a large site, the start page becomes a settings page - the primary purpose of it is settings management. But that is not a good approach. The start page should contain only the page related stuff.

To solve the issue, create a separate page type that has only one purpose - storing settings. You can group settings properties or add local blocks to this page type, as I described in my previous article.

[ContentType(GUID = "16BA6D0E-49D1-4A49-95A9-88B7FAE65E63")]
public class SettingsPage : PageData
{
  [Display(GroupName = GroupNames.Header, Order = 10)]
  [UIHint(UIHint.Image)]
  [AllowedTypes(typeof(ImageFile))]
  public virtual ContentReference CompanyLogo { get; set; }

  [Display(GroupName = GroupNames.Footer, Order = 10)]
  public virtual LinkBlock Links { get; set; }
}

Now you can create a page in the root of the site and set required settings. To load and use the page in your code, you can use an extension method from the Geta.EPi.Extensions package GetFirstChild or create one:

public static T GetFirstChild<T>
  this IContentLoader contentLoader, ContentReference contentReference)
    where T : IContentData
{
  return contentLoader.GetChildren<T>(contentReference).FirstOrDefault();
}

Then in your code, use this extension to load settings from the site root.

var settings = _contentLoader.GetFirstChild<SettingsPage>(ContentReference.StartPage);

Multiple sites

As you have the settings page type already created, you need to create new settings pages on each site. Then when you load the settings by using ContentReference.StartPage in your code, it will load the correct settings page for each of your sites.

Global settings

You can use the same approach for global settings. Create a separate page type that will contain global settings. Then create this page in the root of the Episerver instance.

To load global settings, use ContentReference.RootPage as the settings page parent in GetFirstChild method.

var settings = _contentLoader.GetFirstChild<GlobalSettingsPage>(ContentReference.RootPage);

Summary

A custom page type is an excellent tool when you have to separate settings from other site data. You can create a site-specific settings page type, a settings page type that is used in multiple sites, or a page type that is used globally in the whole Episerver instance.

The easiest way to improve the way how settings are displayed for the users (administrators), is by grouping those in tabs. For example, you have several setting properties on the start page, and those are mixed now with other properties.

[ContentType(GUID = "6C709414-18C6-4E97-9B83-7220FA87D05A", Order = 10, AvailableInEditMode = true)]
public class StartPage : PageData
{
    [CultureSpecific]
    public virtual string Header { get; set; }

    public virtual Url FacebookUrl { get; set; }
}

The Header property, in this example, is displayed on the start page, but FacebookUrl is used for the whole site. So the last one is a setting we would not like to see mixed with start page related stuff in UI.

By adding the Display attribute and setting GroupName property on it, we will move the setting property to the separate tab in UI.

[ContentType(GUID = "6C709414-18C6-4E97-9B83-7220FA87D05A", Order = 10, AvailableInEditMode = true)]
public class StartPage : PageData
{
    [CultureSpecific]
    public virtual string Header { get; set; }

    [Display(GroupName = "Site Settings")]
    public virtual Url FacebookUrl { get; set; }
}

It is also a good approach to extract group name constants into a separate class and add GroupDefinitions attribute so that Episerver will pick it up. For more info, read Episerver documentation.

[GroupDefinitions]
public static class GroupNames
{
    [Display(GroupName = "Site settings", Order = 10)]
    public const string SiteSettings = "SiteSettings";
}

Grouping settings with local blocks

While grouping with a Display attribute allows separating settings in UI, in code, the setting properties are kept together with content properties. One way to work around this issue is by creating blocks and adding those as properties to the start page.

Create a block first.

[ContentType(GUID = "13304E95-B697-444E-B0D4-F8806B70BF20")]
public class SettingsBlock : BlockData
{
    public virtual Url FacebookUrl { get; set; }
}

And then add it to the start page.

[ContentType(GUID = "6C709414-18C6-4E97-9B83-7220FA87D05A", Order = 10, AvailableInEditMode = true)]
public class StartPage : PageData
{
    [CultureSpecific]
    public virtual string Header { get; set; }

    [Display(GroupName = GroupNames.SiteSettings)]
    public virtual SettingsBlock Settings { get; set; }
}

As you see, I have kept the Display attribute and set GroupName so that the block with settings is still displayed in a separate tab.

Now, when you need to use settings in your code, you can just pass SettingsBlock around and do not mess with other start page related settings.

var startPage = _contentLoader.Get(ContentReference.StartPage);
var settings = startPage.Settings;

DoSomething(settings);

Summary

As you see, there are some simple ways how to improve settings on your site for both - end-users in UI and developers in code. Though in large projects, it is not enough to add grouping or extract settings into a local block. You might need a more advanced approach. But that's for another time.

P.S. Check out Alf's blog about his approach to managing settings.

In the ASP.NET world (.NET Framework, not Core), the most common place for settings is the appSettings section in the Web.config file. You can configure solution-wide settings here. It is possible to add transformations for different environments where you are deploying the application.

Also, you can add "partial" settings in a separate file. This is useful when each developer has their own settings. Just add the "partial" file to the .gitignore, and in the Web.config on the appSettings tag, add file attribute that points to your "partial" settings file.

<appSettings file="appSettings.dev.config">
  <add key="MySetting" value="The configuration">
</appSettings>

Once you configured your application, you can retrieve settings using ConfigurarionManager.

var mySetting = ConfigurationManager.AppSettings["MySetting"];

It returns a string value. If you need another type, you have to cast to it.

Pros

• Built-in ASP.NET feature.
• Easy to use.
• Transformations allow creating separate setting values for different environments.

Cons

• Unable to change values in runtime. Requires re-deploy.
• By default, everything is a string. You need to cast to other types.
• Unable to store complex types without serializing to some string format (comma-separated strings, XML, JSON).

Custom settings section in Web.config

A custom settings section is a good alternative to appSettings. It is harder to implement and use, but has several benefits over appSettings. With it, you do not mix your settings with other application settings.

I will not cover creating a custom configuration section here, but Joel Abrahamsson has a excellent article about it: Creating a custom Configuration Section in .NET.

Pros

• Built-in ASP.NET feature.
• Separates your settings from other application settings.
• Transformations allow creating separate setting values for different environments.
• You can create complex types using configuration Elements and Collections.

Cons

• More complex implementation and usage than appSettings.
• Unable to change values in runtime. Requires re-deploy.
• Properties of the configuration are still just strings, and you need to cast those to other types.

Settings on the Start page

It is quite common to use a start page as setting storage in Episerver projects. You can add properties on the start page and configure it to display on the separate tab.

[Display(GroupName = GroupNames.Settings, Order = 100)]
public virtual ContentReference MyLink { get; set; }

Then you can use Episerver API to load the start page and use the setting.

var startPage = _contentLoader.Get<StartPage>(ContentReference.StartPage);
var myLink = startPage.MyLink;

When using a start page, you can define properties of any type Episerver has support. You can use integers, strings, content references, or even use blocks for complex types. A full list of supported types can be found here: Built-in property types.

Another advantage of using the start page is UI. You can easily change settings by opening the start page, changing settings, and then publishing the page. For example, it can be used for "feature switching" to enable/disable some functionality on the site.

Pros

• Easy to use Episerver API.
• Multi-language settings.
• It can be changed in runtime.
• Configure from UI.

Cons

• Environment specific configuration should be configured manually in each environment.
• The start page is not specifically built for settings.

Summary

As you see in this article, each approach for storing and using settings has its advantages and disadvantages. So all approaches also have their use cases.

appSettings and custom configuration sections are great for a configuration that differs by the environment. Also, you would not want to setup settings that often change in Web.config. So this is the right place for settings that are required for 3rd party API integration, some connection details, etc.

The start page can be used for settings that you might change often or should be changed at runtime. As I mentioned previously, it is the right place for "feature switching." Also, you would not want to setup settings on the start page when you need those different in different environments.

The right decision where and how to store settings should be made by a project team depending on requirements.

In the next article, I will describe other options you can use and better organize settings in Episerver.

The only way to get the percentage value of the promotion is by loading the promotion by a reference and then getting its value.

public static decimal GetDiscountValue(this PromotionInformation promotionInfo, IContentLoader contentLoader)
{
    if (promotionInfo.RewardType != RewardType.Percentage)
    {
        return promotionInfo.SavedAmount;
    }

    if (contentLoader.TryGet<PromotionData>(promotionInfo.PromotionGuid, out var promotion)
        && promotion is IMonetaryDiscount monetaryDiscount)
    {
        return monetaryDiscount.Discount.Percentage;
    }

    return promotionInfo.SavedAmount;
}

Here I have created an extension method to get the correct value based on a reward type. When the reward type is not a percentage, return saved amount value from the promotion. Otherwise, load the promotion and return percentage value. Only the promotion of IMonetaryDiscount can have a percentage value.

Now you can use this method to get a percentage or monetary value like this:

public void WorkOnPromotionValue(IOrderForm orderForm, IContentLoader contentLoader)
{
    var promotion = orderForm.Promotions.First();
    var value = promotion.GetDiscountValue(contentLoader);

    if (promotion.RewardType == RewardType.Percentage)
    {
        var percentage = value;
        // Do some work with percentage ...
    }
    else
    {
        var money = value;
        // Do some work with money ...
    }
}

It would be much better if Episerver would store percentage value in the order too. Promotions might be removed, and it will not be possible to get the percentage value anymore. And promotions are removed quite often as too many promotions severely affect the site's performance when calculating discounted price.

[ScaffoldColumn(false)]

This does not work for the Category property though. To fix it, you can add an editor descriptor similar to Joel's but instead of filtering on content types, filter on ScaffoldColumn and use its Scaffold value:

[EditorDescriptorRegistration(TargetType = typeof (CategoryList))]
public class HideCategoryEditorDescriptor : EditorDescriptor
{
    public override void ModifyMetadata(
        ExtendedMetadata metadata,
        IEnumerable<Attribute> attributes)
    {
        var attrs = attributes as Attribute[] ?? attributes.ToArray();
        base.ModifyMetadata(metadata,  attrs);

        if (metadata.PropertyName != "icategorizable_category") return;

        var scaffoldAttribute =
            attrs
            .SafeOfType<ScaffoldColumnAttribute>()
            .FirstOrDefault();
        if (scaffoldAttribute == null) return;

        metadata.ShowForEdit = scaffoldAttribute.Scaffold;
    }
}

NOTE: I am using SafeOfType extension method from the Geta.Net.Extensions library.

Now you can use ScaffoldColumn to control the visibility of the Category property.

[ScaffoldColumn(false)]
public override CategoryList Category { get; set; }

Here I am overriding a category property from the base class and applying the attribute.

We have item level discounts on two categories where one category has a 30% discount and the second one has a 50% discount. Then we defined an order level discount of 40% when a coupon code is applied. The order of discounts is 50% -> 40% -> 30%.

When we tried to add products from both categories and then apply a coupon code, we got a validation error that it is an invalid discount combination.

The research and the solution

Episerver support sent us a Quicksilver example where this setup worked but with a small difference - 40% discount was an item level discount. We tried to re-create the same setup, but it still did not work.

After some research, I found that Episerver support changed Quicksilver code, which applies discounts. They have changed the exclusion level from Order to Unit when calling ApplyDiscounts on the cart.

cart.ApplyDiscounts(_promotionEngine, new PromotionEngineSettings
{
    ExclusionLevel = ExclusionLevel.Unit
});

The default value for ExclusionLevel is Order. So the combination we tried to apply didn't work. Strangely, this is a default value as such discount combinations are common in e-commerce solutions.

So if you need control of combining different discounts on item level, always use ExclusionLevel.Unit.

Thanks to Cuong Phan from Episerver support for help!

Here I have created an extension method to schedule the job to run after ten seconds.

public static class ScheduledJobExtensions
{
    public static void ScheduleRunNow(
      this ScheduledJob job, IScheduledJobRepository scheduledJobRepository)
    {
        job.IntervalType = ScheduledIntervalType.None;
        job.IntervalLength = 0;
        job.IsEnabled = true;
        job.NextExecution = DateTime.Now.AddSeconds(10);

        scheduledJobRepository.Save(job);
    }
}

You can use this extension method like this:

var job = _scheduledJobRepository.Get(new Guid(MyJob.Guid));
job.ScheduleRunNow(_scheduledJobRepository);

With a few SQL scripts, you can get all you need. The first thing to find out is the ID of the content area property. You can find it in the tblPropertyDefinition by querying it on fkContentTypeID column (if you do not know the ID of the content type, find it in the tblContentType table).

SELECT *
  FROM [dbo].[tblPropertyDefinition]
  where fkContentTypeID = 100

In the results, find your property and use it's pkID value in the next query.

In the tblContentProperty table, Episerver stores values of all properties. You can easily get values for all properties by querying by content ID on the fkContentID column and property definition ID on the fkPropertyDefinitionID column (the value you get in the previous step). The easiest way to get a content ID is by going into the Episerver edit mode and check the ID under the content properties.

Once you get all IDs, run the query. To get values of a content area, you should look into LongString column.

SELECT [LongString]
  FROM [dbo].[tblContentProperty]
  where fkPropertyDefinitionID = 800 and fkContentID = 9000

Episerver stores content area data in an XML format which looks like Html. Each item in the content area is represented as a DIV tag with some attributes. I was interested only in two - data-contentguid and data-contentname. The first attribute is a GUID which links to the content in the content area and the second helps to identify an item by the name.

<div
    data-classid="36f4349b-8093-492b-b616-05d8964e4c89"
    data-contentgroup=""
    data-contentguid="00000000-0000-1234-0000-000000010000"
    data-contentname="Fancy stuff">{}</div>

In our case, product GUIDs were generated in a specific format and those where changing in some cases. In this example, it would be 1234 part. Once we found the issues in IDs, we could easily fix it with a script.

UPDATE tblContentProperty
SET LongString = REPLACE(LongString, '00000000-0000-1234-0000-', '00000000-0000-0000-0000-')

I know that it might be dangerous to modify Episerver DB directly, but we haven't risked much as products in content areas were not visible anyway. Luckily, this fixed our issues.

There is another table which might be useful when researching issues with content areas. It is tblContentSoftlink table.

SELECT *
  FROM [dbo].[tblContentSoftlink]
  where fkReferencedContentGUID = '00000000-0000-1234-0000-000000010000'

There is one important column in this table - ContentLink. You can find a matching content link for a content GUID in it. In our case, we still saw a content link and it was a valid one - the content existed in the DB. But once we edited content in the edit mode without touching our content area, the content link became empty. The data in the content area still remained (in the tblContentProperty table).