Forem: WiredViews

Bits of Xperience: Displaying Rich Text After a Form Submission

Sean G. Wright — Tue, 06 Sep 2022 12:54:54 +0000

Kentico Xperience's Form Builder enables marketing professionals to quickly build and manage forms in a no-code UI for use across their website 👩🏾‍💼.

The experience for site visitors submitting a form can be customized for successful submissions 👍🏽.

Let's look at what's possible and how a few lines of customized code can extend the functionality even more 😮!

📚 What Will We Learn?

What happens after a Form is submitted
How to customize the Form management UI
How to customize Razor Class Libraries

❓ What Happens After a Form is Submitted?

Forms on a website are one of the most common ways for marketers to engage with visitors.

Let's take the Dancing Goat demo site Contact Form as an example:

When a visitor fills out this Form and submits it, what exactly happens 🤔?

If the form is not valid (based on form field validation) Xperience will re-render the form with validation error UI and messages
If the form is valid, Xperience looks for an existing form entry for the submitter (if the visitor is identified as an existing Contact) and updates it, or adds a new Form submission to the database.
If the Form's Redirect Url is populated, redirect the page to a new URL (usually to display some "thank you" content).
If Form's Display Text is populated, return Display Text and replace the Form with the Display Text.

Redirecting to a new page gives a marketer a lot of control over the visitor's experience 💪🏻, but it also requires maintaining an additional page on the site 😞.

Using the Display Text is simpler and more convenient 🤗!

Unfortunately, the Display Text field only accepts plain text. What if we want to respond to a form submission with a helpful message, links, and maybe a Call To Action with an accessible design 🤷🏼‍♂️?

It seems as though we'll need to customize what kind of content we can author here and how it's displayed on the site after a submission 🤓!

🗃 How to Customize the Form Management UI

The first thing we need to look for is a way to change the Display Text field's Text input to a Rich Text input.

This UI element can be found at CMS\CMSModules\BizForms\Tools\BizForm_Edit_General.aspx:

The key customization we need to make to this file is to register a new "Rich Text" User Control (called HtmlAreaControl) at the top of the file:

<%@ Register 
    Src="~/CMSFormControls/Basic/HtmlAreaControl.ascx"
    TagName="HtmlArea" 
    TagPrefix="cms" %>

With that registration added, we can refer to the control further down the file, replacing the <cms:LocalizableTextBox /> currently being used for Display Text input with a <cms:HtmlAreaControl />:

<cms:CMSRadioButton ... />

<div class="selector-subitem">
    <cms:LocalizableTextBox ID="txtDisplay" runat="server" MaxLength="200" />
</div>

is replaced by:

<cms:CMSRadioButton ... />

<div class="selector-subitem">
    <cms:HtmlArea ID="txtDisplay" runat="server" MaxLength="200" />
</div>

With these two changes, we can rebuild the CMS application and go back to the Form "General" tab and add Rich Text as our Display Text 🦾!

📅 How to Customize Razor Class Libraries

Even though we're now storing Rich Text as our Form's Display Text, we won't get very far if we don't change how that Display Text is rendered on the live site 😏.

Fortunately, ASP.NET Core includes a feature that allows us to override a View included in our project from a Razor Class Library by adding a View file with the exact same name and path as the file from the Razor Class Library 🧐.

The View that controls how the Form Display Text is rendered after a successful submission is in the Razor Class Library at the following path:

~/Views/Shared/Kentico/Widgets/FormWidget/_FormWidgetTextConfirmation.cshtml

We don't have a file at that path in our project, so let's create a new empty one 🙃.

Make sure you use the same path and filename, otherwise ASP.NET Core will see your View as a new one and not a replacement for the View coming from the library!

The Razor in the original View from the library looks this like:

@model string

<div class="formwidget-submit-text">@Model</div>

Which we are going to replace with the following:

@model string

<div class="formwidget-submit-text">@Html.Raw(Model)</div>

By rendering the Model with Html.Raw() we ensure our Rich Text Display Text won't be escaped when displayed on the page.

At this point we can rebuild our ASP.NET Core application and we're all set 🙌🏿!

🏁 Conclusion

With our 2 simple customizations, we can try out the Contact form to see our Rich Text message displayed on the page:

It worked 🎉!

We can use any content or design to our Display Text that can be authored in Rich Text and craft a "richer" experience (pun intended 😆) without having to go through the process of creating a completely separate page to redirect to.

As always, thanks for reading 🙏!

References

Form Builder - Xperience Docs
Form Builder field validation - Xperience Docs
Form Builder Smart Fields - Xperience Docs
Overriding Razor Class Library Views - ASP.NET Core Docs

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like:

Bits of Xperience: Reducing CLS when Rendering Images

Sean G. Wright — Tue, 31 May 2022 16:10:05 +0000

Kentico Xperience sites allow marketers and content managers to author content and build pages that display text, images, and anything else that HTML supports 😁.

There are multiple ways to add images to content in Xperience:

Embed in Rich Text
Custom Page Builder Component (Widget or Section)
Rendered with Razor in a Page view or Template

These images can come from multiple sources:

Media Library
Attachments
Meta files (for SKUs)
Form Submissions

No matter which rendering approach or content source combination we are using for images on our sites, we'll want to make sure we always render those images with the appropriate HTML attributes, and these days that includes the width and height attributes.

But why 🤔?

📚 What Will We Learn?

What is Cumulative Layout Shift (CLS)?
How width and height attributes prevent Layout Shift?
How do we get this information programmatically?
Why should we always retrieve image content from the database?

🌊 Cumulative Layout Shift (CLS)

Have you ever heard of Cumulative Layout Shift? It is defined (by Google) as follows:

CLS is a measure of the largest burst of layout shift scores for every unexpected layout shift that occurs during the entire lifespan of a page.

A layout shift occurs any time a visible element changes its position from one rendered frame to the next. (See below for details on how individual layout shift scores are calculated.)

We've all experienced this on websites. Something on the page finally loads and a button moves, or the text we're reading shifts out of the viewport.

Not only is this extremely annoying 😖, but Google uses it as a quality indicator for websites. More CLS means a worse user experience and Google takes that into account for scoring in PageSpeed Insights, which means it impacts search ranking 😮.

So, now that it's clear we want to reduce CLS on our sites, how does this factor into displaying images with Kentico Xperience?

Reducing CLS with Images and `width` and `height` HTML Attributes

Images can be a major cause of CLS 🙁 because the browser doesn't know an image's dimensions until it's been fully downloaded. While the image is being downloaded, the browser's rendering engine doesn't know how much space to allocate for it on the page. Once it finishes downloading, the browser re-renders, moving other content around to give the image the space it needs 😒.

It should be clear now why we shouldn't be rendering images in Xperience with just a src attribute:

<img src="@Model.ImagePath">

This will all but guarantee CLS in most situations 😭.

However, browsers have been using width and height attributes to pre-allocate space for images for awhile now 🧐.

Check out this great article on the topic on Smashing: Setting Height And Width On Images Is Important Again and it's follow up How To Fix Cumulative Layout Shift (CLS) Issues

If we know the width and height values for an image and add those attributes/values when rendering it, we can help prevent CLS by letting the browser know how much space (vertically) the image will need based on the image's aspect ratio computed from these two values 👏🏾.

Getting an Image's Dimensions in Xperience

Thankfully, Xperience stores all uploaded image's dimensions in the database 🙏🏽. However, since there are multiple ways to store and display images in Xperience, we'll need multiple techniques for retrieving an image's dimensions.

Note: Xperience doesn't treat .svg files as images, which means we need to customize its behavior to capture SVG image dimensions when they are uploaded to a site.

We can use the Xperience SVG Media Dimensions library to do this for us automatically!

Image Dimensions and Media Files

The Media Library is probably the best place to store and manage images in Xperience so we'll use it as an example 👍🏿.

To select files from the Media Library for Page Type fields, you'll probably use the Media Selection Form Control:

This will display a path on the page's Content tab for this control and a preview of the image:

Retrieving an image from the media library by full path isn't a great developer experience, so fortunately @mattnield wrote a Regex several years ago that is able to retrieve the media file's FileGUID from the path 💪🏼.

With the FileGUID retrieved, we can query the image's content from the database:

HomePage? page = (await pageRetriever.RetrieveAsync<HomePage>(
   query => query.TopN(1), 
   cancellationToken: token))
   .FirstOrDefault();

if (page is null || 
    string.IsNullOrWhiteSpace(page.Fields.HeroImageMediaFilePath))
{
   return;
}

string pattern = @"[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}";

Guid mediaFileGUID = Regex.Match(
    page.Fields.HeroImageMediaFilePath, 
    pattern, 
    RegexOptions.IgnoreCase).Value;

MediaFileInfo? file = (await mediaFileInfoProvider.Get()
    .WhereEquals(
        nameof(MediaFileInfo.FileGUID), 
        mediaFileGUID)
    .GetEnumerableTypedResultAsync(cancellationToken: token))
    .FirstOrDefault();

if (file is null)
{
   return;
}

// use Media File values ...

Now that we have our full MediaFileInfo we can use all of its data to render our <img> element 🙌.

Assuming we have an ImageViewModel class defined like this:

public class ImageViewModel
{
    public ImageViewModel(
        MediaFileInfo file,
        IMediaFileUrlRetriever urlRetriever)
    {
        Path = urlRetriever.Retrieve(file).RelativePath;
        AltText = file.FileDescription;
        Title = file.FileTitle;
        Width = file.FileImageWidth;
        Height = file.FileImageHeight;
    }

    public string Path { get; }
    public string AltText { get; }
    public string Title { get; }
    public int Width { get; }
    public int Height { get; }
}

We can render our image in Razor as follows:

<img src="@Model.Path"
     alt="@Model.AltText"
     title="@Model.Title"
     width="@Model.Width"
     height="@Model.Height">

Awesome! Layout shift avoided and CLS reduced! 🎉🥳🎊

Always Retrieve the Full Image!

You might think, "This makes sense for images at the top of the page, but what about images at the bottom? They won't impact CLS, so this is a lot of extra work for little benefit."

First, if we display an image as part of a Widget, we don't know where on the page that Widget will be added and different devices' viewports might place that content in different locations on the page. We should code defensively and always retrieve these values from the database 😊.

Second, and far more importantly, we should always retrieve the full image content from the database for accessibility 😎!

All images in Xperience have Title and Description fields, which translate to the title and alt HTML attributes. If we want accessible sites (I'd argue that accessibility is one of the 7 things we can't skip when building a website), then we need to include these values on every informational image we render (background images that are for design don't have the same requirements).

This means we are going to have to retrieve the image content anyway 🤷🏽‍♀️, so it's really no extra work to get the width and height values.

🏁 Conclusion

Cumulative Layout Shift (CLS) is "a measure of the largest burst of layout shift scores for every unexpected layout shift that occurs during the entire lifespan of a page". This measurement represents some of the user experience visitors will have when they visit a page and can negatively impact our page's search rank (SEO) 🙄.

The browser doesn't know how much space to allocate for images until they are fully downloaded, so images often impact CLS on sites. To help prevent Layout Shift for images we can add the image's width and height values as HTML attributes to the <img> element. This tells the browser how much space to allocate for the image based on its aspect ratio 🧠.

To add these values with a Kentico Xperience site, we'll need to retrieve the image's content from the database (as opposed to only the image's path).

To improve the accessibility of our sites, we want to include alt text on our images. This content, authored by content managers and marketers, is stored in the image content in the database 🤗.

So, while adding width and height values to an <img> might add some complexity to our code, we should be retrieving an image's content from the database anyway to ensure our sites are accessible 😉!

As always, thanks for reading 🙏!

References

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like:

Bits of Xperience: Supercharged Page Custom Data Fields

Sean G. Wright — Mon, 27 Sep 2021 14:12:57 +0000

Kentico Xperience's custom Page Types let us model a site's content using a combination of powerful built-in Form Controls and the flexible structuring of information in a site's Content Tree.

Usually, with Page Type fields, each field maps to one value (as a column in a database table), and each Page Type has a unique set of fields. But, what if we want to store multiple fields in a single database column, or have multiple Page Types that store data in a single location, making it easy to query 🤔?

There might not be an out-of-the-box solution, but fortunately, with a little code and configuration 🤓, we can use Page "Custom Data" to achieve both of these things.

If you want to jump to the solution, check out our new NuGet package that does all the coding for you, Xperience Page Custom Data Control Extender.

📚 What Will We Learn?

What are Page "Custom Data" fields?
What do the "Custom Data" Page fields lack?
Using Global Events with Page "Custom Data"
Using Custom Form Controls and a Control Extender
Storing Page data directly in "Custom Data" fields

❓ What are Page "Custom Data" fields?

Before we get going, let's level set. Page "Custom Data" fields are the DocumentCustomData column in the CMS_Document table and the NodeCustomData column in the CMS_Tree table.

Anything in, or related to, the CMS_Tree table is going to apply to all cultures for a Page in the Content Tree, and likewise, anything in, or related to, the CMS_Document table is going to be specific to a single culture. Many sites only have a single culture, so this distinction might not be something you're used to thinking about 🤨.

Read more about the Kentico Xperience Page database architecture 🧐.

All "Custom Data" database columns (there are many in non-Page ones Xperience) have an XML structure, and the C# API to interact with them works with a XmlData container behind the scenes, almost like a string-keyed dictionary.

"Custom Data" columns let us switch from a relational database architecture to more of a document structure where the schema of the data isn't defined in the database, but instead in our code.

It would be great 👍🏾 to leverage this alternate way of storing data to achieve what was discussed earlier (multiple values per column and Pages storing field values for multiple Page Types in the same location, instead of separate Page Type database tables).

🗃 What do the Page "Custom Data" Page Fields Lack?

First, let's review why we can't 😞 use Page "Custom Data" fields as they currently exist in Xperience.

If we look at the the documentation on the features of the field editor, which is used for creating fields for custom Page Types, we can see there are a couple options for the "Field type". The one we are interested in is the "Page Field":

Page field – only available for page type fields. Allows you to choose a general page column from the CMS_Tree or CMS_Document table, and link it to the page field.

When creating a new Page Type field and selecting a Field type of Page field we can select either Page fields or Node fields for the Group. This equates to columns from the CMS_Document and CMS_Tree tables.

If we select Page fields and then pick the Field name of DocumentCustomData, we can start interacting directly with this value for each Page of the given Page Type 😀.

Because the XML schema of these fields is flexible, there's no special "Custom Data" Form Control 😦 that let's us modify that XML in a way that is friendly to Content Managers.

The best we can do is a Rich Text editor:

But it falls way too short of something usable for Content Managers 😣:

So what are we going to do if we want to leverage the schema flexibility of "Custom Data" fields for a Page? What Form Control gives us a good Content Management experience? Do we have to build a bunch of custom Web Forms Form Controls ☠?

📅 Using Global Events and Page "Custom Data"

Fortunately there's a couple different ways we can approach this problem 😅.

We already have a bunch of pre-built Form Controls which are designed for ease-of-use for Content Managers. Let's make sure our solution includes those 👏🏼 and doesn't require us to rewrite them!

Let's create a new field on our Page Type named ArticleIsInSitemap, using all the standard Page Type field functionality:

If we create new fields on our Page Type and use the appropriate standard Form Controls for those fields, we can get a solid Content Management experience, but the values go into individual database columns in each Page Type's database table 🤦🏽‍♀️ instead of the Page "Custom Data" columns.

Thankfully, Kentico Xperience has a full set of Global Events that allow developers to react to things happening within the system 👨🏿‍🔬. We can use these events to copy data from our Page Type fields to the "Custom Data" XML structures of the Page.

Let's create a Custom Module that will give us a place to react to these events:

using CMS;
using CMS.DataEngine;
using CMS.DocumentEngine;
using CMSApp;

[assembly: RegisterModule(typeof(DocumentEventsModule))]

namespace CMSApp
{
    public class DocumentEventsModule : Module
    {
        public DocumentEventsModule() : 
            base(nameof(DocumentEventsModule)) { }

        protected override void OnInit()
        {
            base.OnInit();

            DocumentEvents
                .Insert
                .Before += Insert_Before;

            DocumentEvents
                .Update
                .Before += Update_Before;
        }

        private void Update_Before(
            object sender, DocumentEventArgs e) => 
            SetValuesInternal(e);

        private void Insert_Before(
            object sender, DocumentEventArgs e) =>
            SetValuesInternal(e);
    }
}

Both of the event handlers above let us run our logic when any Page is inserted or updated with the following method:

private void SetValuesInternal(DocumentEventArgs e)
{
    if (!(e.Node is Article article))
    {
        return;
    }

    article
        .DocumentCustomData
        .SetValue(
            nameof(Article.Fields.IsInSitemap), 
            article.Fields.IsInSitemap);
}

And that's it! Every time an Article is inserted into the Content Tree or updated, the value in ArticleIsInSitemap will be copied to an XML element in CMS_DocumentCustomData 😊, which will look like this in the database:

<CustomData>
  <IsInSitemap>true</IsInSitemap>
</CustomData>

What's the benefit here? Don't we already have the value in the DancingGoatCore_Article table's ArticleIsInSitemap column?

Well, for data that determines whether or not a Page is in the sitemap, we want to be able to query across all Pages of the site, not just Articles, so that we generate the correct XML sitemap.

If we have a column in each table for all of our custom Page Types, we'd end up with a real ugly SQL UNION to get all the Pages in the sitemap. By copying the value to DocumentCustomData, we ensure the full sitemap can be generated by only querying the CMS_Document table 💪🏻:

SELECT *
FROM CMS_Document
WHERE CAST(DocumentCustomData as XML).value('(//CustomData/IsInSitemap/text())[1]', 'bit') = 1

Checkout Microsoft's documentation to read about querying XML in SQL

This is great 👍🏾! But it would be really great if we didn't have to have an extra database table column per-Page Type and duplicate this data. We would prefer to write directly to the Page "Custom Data" field 😏.

🎛 Custom Form Controls and Control Extenders

Lucky for us, Kentico Xperience provides a convenient feature in the CMS architecture - Control Extenders.

Control Extenders let us enhance the functionality of inherited Form Controls. But what does that mean?

We can create new Form Controls in the Administration application, with either new code or inheriting the code and functionality from an existing Form Control. The 2nd option is preferable because it means less work for us 😄!

When we create a new Form Control that inherits from another, we can apply a Control Extender to it. A Control Extender is a component that wraps the original Form Control and gets to intercept interactions with the Control 🧐.

This is a valuable feature for us, because it will let us source the Control's value from DocumentCustomData when it is read and write it to DocumentCustomData when the Control value is updated - all without modifying the code or functionality of the original control. We can also apply this Control Extender to any inheriting Form Control 😮.

In summary, this is what we want to accomplish:

✔ Create a Control Extender that redirects interactions with the Form Control's value to the DocumentCustomData field and store the value in an XML element with the same name as the field's name
✔ Create a new Form Control that inherits from the standard Check box Form Control and apply the Control Extender to the new Form Control
✔ Use the new Form Control as the control for our Article Page Type IsInSitemap field

🏗 Control Extender

The code for the Control Extender is pretty simple:

public class CustomDataControlExtender : 
    ControlExtender<FormEngineUserControl>
{
    public override void OnInit()
    {
        // logic here
    }
}

There are multiple events the Control emits that we can register event handlers for and when the underlying Form Control initializes, we register our event handlers in Control_Init.

public override void OnInit() => 
    Control.Init += Control_Init;

private void Control_Init(object sender, EventArgs e)
{
    Control.Form.OnGetControlValue += Form_OnGetControlValue;
    Control.Form.OnAfterDataLoad += Form_OnAfterDataLoad;

    Control.Form.FieldControls.Add(Control.Field, Control);
    Control.Data.ColumnNames.Add(Control.Field);
}

We are going to be creating our Page Type field as a "Field without database representation", which means it won't be listed in the FieldControls or ColumnNames collections that get processed when we load/save our Form, so we explicitly add it.

This way the Form treats our field as though it needs to be persisted/retrieved just like the other ones.

private void Form_OnAfterDataLoad(object sender, EventArgs e)
{
    if (!(Control.Data is TreeNode page))
    {
        return;
    }

    Control.Value = page
        .DocumentCustomData
        .GetValue(Control.Field);
}

private void Form_OnGetControlValue(
    object sender, FormEngineUserControlEventArgs e)
{
    if (!(Control.Data is TreeNode page))
    {
        return;
    }

    if (e.ColumnName.Equals(
        Control.Field, 
        StringComparison.InvariantCultureIgnoreCase))
    {
        page.DocumentCustomData.SetValue(
            Control.Field, Control.Value);
    }
}

Then we define two event handlers - the first supplies the Form Control value from the correct Page "Custom Data" field when the value is loaded by the Control, and the second accepts the value coming from the Control and stores it in the correct Page "Custom Data" field.

After our interception, the Page gets created or saved and the field's value is saved along with it, except it's inside DocumentCustomData and not a Page Type specific database column 🤩.

👵🏽 Inheriting a Form Control

Inheriting from an existing Form Control and applying a Control Extender only takes a few steps!

First, navigate to the "Administration interface" module in the CMS application:

Then create a new "inheriting" Form Control, using the Check box Form Control as the source:

Be sure to select the Control Extender you just created!

Finally, select the places where this Form Control can be used. For our example it will be for "Boolean (Yes/No)" fields for "Page Types":

📃 Using a Page "Custom Data" Form Control

Now we can create the new field for our Page Type 😊!

Be sure to select "Field without database representation" for the Field type (otherwise the value will be saved in a newly created database table column for the Page Type 😬) and use our new extended Form Control (otherwise the value won't be saved at all).

Whatever we name this new field will end up being the XML element that the value is stored in, so a field named ABC would end up as <CustomData><ABC>value</ABC></CustomData>:

And that's it! When we save a Page of this Page Type, this specific field will only be saved to DocumentCustomData.

We can add as many "Custom Data" fields to a Page Type as we want, and if we define the same field on multiple Page Types, they'll all put data of the same XML schema in our CMS_Document.DocumentCustomData database column.

🏁 Conclusion

I hope by now both the motivation and process for using Page "Custom Data" fields as the backing store of Page Type fields are clear 🔍.

There's a few steps to set everything up - create a Control Extender, define new inheriting Form Controls using the Control Extender, and add a fields to Page Types using the extended Form Control - but the initial setup definitely pays off. It's worth noting the first step (creating a Control Extender) only needs performed once, and the second (creating an extended Form Control) only once per Form Control type (eg Text Box, Check Box, Page Selector).

Our "Sitemap" example saves us from performing a large SQL UNION when we generate a site's XML sitemap, but that's not the only use case.

What about Open Graph metadata values for a Page - wouldn't it be nice to not have to create a separate database column for each value?

Or, a standard field inherited from a base Page Type that we aren't going to be likely to filter in SQL - like a 'primary image path'.

We could even make mixins, letting multiple Page Types share sets of fields and then access those field values across Page Types by querying the CMS_Document table only 🧐.

Are you thinking about implementing this yourself? Well, it's dangerous to go alone...

So, take this... the Xperience Page Custom Data Control Extender, a NuGet package containing an enhanced version of the above Control Extender with detailed setup instructions 👐.

As always, thanks for reading 🙏!

References

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like:

Bits of Xperience: The Hidden Cost of IPageUrlRetriever.Retrieve

Sean G. Wright — Mon, 28 Jun 2021 13:19:38 +0000

There's a lot of new, helpful types and methods in Kentico Xperience 13.0... but it can sometimes be difficult to know when each should be used 🤔.

Let's look at the simple (or is it?) example of the IPageUrlRetriever interface and its Retrieve() method.

📚 What Will We Learn?

What IPageUrlRetriever does
The multiple overloads of the Retrieve() method
The hidden difference between each overload
The best way to retrieve Page URLs

🎣 What is the IPageUrlRetriever?

Using Kentico Xperience's Content Tree based routing is the option most developers choose. It enables the ability to have some Pages in the Content Tree not participate in URL generation, and also ensures that culture is included in URLs based on the site's settings.

All of this means that generating URLs correctly can get a little tricky 😅!

Fortunately, Kentico Xperience helps us out by providing the IPageUrlRetriever interface which has 1 method, Retrieve().

This method returns an instance of the PageUrl type which is defined as:

//
// Encapsulates page relative path and absolute URL.
public class PageUrl
{
    public PageUrl();

    //
    // Relative path (starting with ~/) of the page.
    public string RelativePath { get; set; }

    //
    // Absolute URL of the page.
    public string AbsoluteUrl { get; set; }
}

We can use this PageUrl instance to render links to other Pages in our Razor Views.

However, there are multiple overloads of the Retrieve() method and they have very different use-cases 😮.

🧙🏽‍♀️ Which Method Do We Choose?

Here are all the overloads of IPageUrlRetriever.Retrieve(), with their XML doc comments summary included:

// Retrieves URL for given page
PageUrl Retrieve(TreeNode page, bool keepCurrentCulture = true);

// Retrieves URL for the given page in the given culture.
PageUrl Retrieve(TreeNode page, string cultureCode);

// Retrieves URL for a page based on given properties.
PageUrl Retrieve(string nodeAliasPath, bool keepCurrentCulture = true);

// Retrieves URL for a page based on given properties.
PageUrl Retrieve(string nodeAliasPath, string cultureCode, string siteName = null);

It looks like Kentico Xperience is giving us a lot of flexibility here. We can either supply a full TreeNode instance or, just the nodeAliasPath.

That's convenient! If we know there's always an /About Page in the Content Tree, we can make a call like:

PageUrl pageUrl = retriever.Retrieve("/About");

This will give us access to the correctly generated Page URL, and we don't have to query for the TreeNode, which means one less database round-trip 😃 (or does it?)

So, we probably feel pretty confident 😤 in using Retrieve(TreeNode node, ...) when we have the TreeNode instance anyway, and using Retrieve(string nodeAliasPath, ...) when we only know where in the Content Tree the Page is or when we get the Node Alias Path from some other Page's field.

⚔ Retrieve(string) vs Retrieve(TreeNode)

In this situation Xperience asks for what it needs but lets us provide less, however there's no free lunch and the convenience provided to us has a cost 🤨!

The IPageUrlRetriever is implemented by the Kentico.Content.Web.Mvc.PageUrlRetriever internal class. When we call Retrieve(string nodeAliasPath, ...) the PageUrlRetriever uses IPageSystemDataContextRetriever.Retrieve() internally to get the 'page data' that matches the nodeAliasPath we provided:

/// <summary>
/// Provides an interface for retrieving the page based on given parameters for system purposes.
/// </summary>
public interface IPageSystemDataContextRetriever
{
    // ...

   TreeNode Retrieve(SiteInfoIdentifier site, string nodeAliasPath, string cultureCode, bool latest);
}

IPageSystemDataContextRetriever.Retrieve() is fortunately cached for 10 minutes, so repeated uses of IPageUrlRetrieve.Retrieve(string nodeAliasPath, ...) won't result in multiple database calls, but the first call absolutely does hit the database because it needs more information, than what we provided, to generate the correct URL.

This is an important point to understand... Kentico Xperience provides many different ways to accomplish the same goal, which is a good thing because we can choose the right one for our use-case. At the same time, if we choose the wrong approach for our use-case, we might end up taking a performance hit we didn't intend 😬!

How bad can it get? Let's say we are generating URLs for 100 products displayed on a Page using IPageUrlRetriever.Retrieve(string nodeAliasPath, ...). This means we are executing at least 100 database queries just to get URLs! Add on to this all the querying we did to get the Product information and images! Ooof 😖!

This is commonly known at the N + 1 Querying Problem and is often seen with Object-Relational Mapping tools like Entity Framework Core or ... Kentico Xperience's APIs 😋.

🔥 More Pitfalls 💣

Let say we've avoided the N + 1 query by using the alternative overload of IPageUrlRetriever.Retrieve(TreeNode node, ...) so that Kentico Xperience doesn't have to go and fetch all the nodes independently.

If we still have to get our Pages from string nodeAliasPath values, we can use the WhereIn(string columnName, ICollection<string> values) method defined on WhereConditionBase to query for all TreeNode objects that match set of nodeAliasPath values we have. This would be a big query, but at least it's 1 query and not 100.

Since we've found the correct API for our use-case, we should be all set now, right? git commit and deploy 😎!

Unfortunately, we could now run into a second problem 😫.

In Kentico Xperience MVC (compared to older Portal Engine sites), the nodeAliasPath is not the true URL even if parts of it match a URL for a Page. Instead, all generated URL values are stored in the CMS_PageUrlPath table 🤓 in the database and the actual path is in the PageUrlPathUrlPath column (what a tongue twister!)

Without this data, we cannot generate valid Page URLs.

This means that when we pass a TreeNode to IPageUrlRetriever.Retrieve(TreeNode node, ...), internally it has to check if the PageUrlPathUrlPath field is in the TreeNode's internal data set of field/value pairs. If the value is not populated, then Kentico Xperience has to query the database for it:

PageUrlPathInfo.Provider.Get()
  .WhereEquals("PageUrlPathNodeID", page.NodeID)
  .WhereEquals("PageUrlPathCulture", cultureCode);

In addition to having this field populated, the culture of the TreeNode retrieved from the database needs to match the culture of the URL we are trying to generate.

If either the PageUrlPathUrlPath is missing or the cultures don't match, we have to make yet another database call for the URL data, and as far as I can tell, this query is not cached 😨.

So we're in another situation where we could be making an additional 100 database queries (and if we were using nodeAliasPath that means at least 200 database calls!) to get Page URLs.

🏆 Optimal URL Generation

Fortunately, there's a nice extension method WithPageUrlPaths(), in the CMS.DocumentEngine.Routing namespace, for IDocumentQuery that ensures the CMS_PageUrlPath table is joined when querying for our TreeNodes 🤩.

If we had a collection of NodeGUID values (or string nodeAliasPath values) that referenced Pages in the Content Tree that we wanted to generate URLs for, I think this would be the best approach:

Guid[] linkedNodeGuids = // ...

var linkedDocuments = await DocumentHelper
    .GetDocuments<TreeNode>()
    .WithPageUrlPaths()
    .WhereIn(nameof(TreeNode.NodeGUID), linkNodeGuids)
    .GetEnumerableTypedResultAsync(cancellationToken: token);

List<(TreeNode Node, PageUrl URL)> nodesAndURLs = linkedDocuments
    .Select(node => (node, urlRetriever.Retrieve(node)))
    .ToList();

With our nodesAndURLs array of tuples we have all the data we need to create links to all those Pages 👏!

Of course, if we instead use Kentico Xperience's IPageRetriever service, the .WithPageUrlPaths() extension gets applied for us automatically:

Guid[] linkedNodeGuids = // ...

var linkedDocuments = await pageRetriever.RetrieveAsync<TreeNode>(
    q => q.WhereIn(nameof(TreeNode.NodeGUID), linkNodeGuids),
    cancellationToken: token);

List<(TreeNode Node, PageUrl URL)> nodesAndURLs = linkedDocuments
    .Select(node => (node, urlRetriever.Retrieve(node)))
    .ToList();

Isn't that nice 😁!

Conclusion

The convenience of the Kentico Xperience libraries help us developers create the applications our businesses need, quickly and with a lot of flexibility 💪🏽.

That flexibility can come at a cost that we might not notice during local development or when a site isn't under heavy load.

Caching helps solve a lot of inevitable performance limitations and mistakes, but it's best if we can make the right choices the first time (especially if its only the difference of 1 method overload vs another 😉).

When trying to get URLs for Pages, especially in bulk, our best choice is to use IPageUrlRetriever.Retrieve(TreeNode node, ...) and then make sure the TreeNode being passed was retrieved from the database using a DocumentQuery that called .WithPageUrlPaths() with the correct culture... otherwise we might end up causing N + 1 (or worse!) querying against the database.

The IPageRetriever.RetrieveAsync() method can at least make sure .WithPageUrlPaths() is applied to our query, so we don't have to remember to do it 😄.

If there are any other APIs you have questions about, let me know in the comments below.

As always, thanks for reading 🙏!

References

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like:

Bits of Xperience: Localizing XHR Requests in Kentico Xperience 13.0

Sean G. Wright — Mon, 18 Jan 2021 15:13:43 +0000

Application and content localization can be tricky, but fortunately, Kentico Xperience 13.0 makes it easy 🤗!

Using Xperience's Content Tree-based routing, we let the platform generate our URLs, inserting the culture code as part of the path.

When our application handles a localized URL, assuming we use the CultureInfo.CurrentCulture (or more likely IPageRetriever) to retrieve our Page's content, we'll be sure display the localized content 💪🏿!

In this post I want to talk about a different scenario...

How do we make sure that any XHR requests made to an API, running in our Xperience application, are also localized, working with and returning the correct content for the current page 🤔?

📚 What Will We Learn?

What is Localization?
How does Xperience set the Page's request culture?
How do our custom API endpoints find the request culture?
What tools can we use to pass the Page's culture on to the API requests?

🌍 What is Localization?

Good ol' Wikipedia says that localization "is the process of adapting a product's translation to a specific country or region."

When we "localize" a response to an HTTP request for a web page, we are making sure that the content returned with that response is correct for the country or region associated with that request. This is often simplified to be the language associated with the request.

For the rest of this post I'm going to use this simplified definition of localization and refer to the language, but there are plenty of other bits of content that need to be localized, like number and date formatting.

Also, the .NET docs have a great discussion on Globalization (building an app so it can support multiple languages) and Localization (adding support for a specific language(s)).

🔍 How does Xperience Figure Out a Request's Culture?

Xperience, like any globalized platform/website, needs to decide on a culture by looking at the incoming HTTP request, because that culture determines the localization of the Page.

There's a lot of places this information could be stored, but the most common are cookies 🍪 or the URL itself.

Xperience's Content Tree-based routing let's developers pick from 2 options:

Using the host: https://site.es/products - Spanish language top level domain
Using the path: https://site.com/es-MX/products - Mexican Spanish language path prefix

The scenario I'm interested in is the latter because it supports having 2 cultures on the same domain.

When looking for the culture in the URL path, Xperience uses route constraints and tokens to pull the culture value out. It has a specific URL pattern, using the path prefix (https://stuff/en-US/more-stuff) which makes it easy to pinpoint the culture 🧐.

In the Xperience ASP.NET Core integration, Xperience has some middleware 🤓 that looks at the incoming request context and figures out what culture to associate with it (based on the settings in the application).

Once it figures out the culture for the request URL, it then sets the culture for the thread/context:

CultureInfo.CurrentCulture = requestCulture.Culture;
CultureInfo.CurrentUICulture = requestCulture.UICulture;

🧭 Finding the Request Culture in API Endpoints

When routing to an ASP.NET Controller or View associated with a Page in the content tree, Xperience does all the traffic management.

But our custom API endpoints aren't associated with anything in the content tree, which means Xperience is hands off 👐!

Let's assume we have a content tree route to a Product Page that is handled by Xperience and we are visiting the (Mexican) Spanish language version of that Page:

GET https://site.com/es-MX/product/apples

We rendered the product id for "apples" into the Razor View for this page, and we use that value to make an XHR request back to our API:

@model ProductViewModel

<h1>@Model.Name</h1> @* This will be "Manzanas" *@

<script>
    const productId = @Model.ProductId;

    fetch(`/api/products/${productId}`)
        .then(resp => resp.json())
        .then(resp => console.log(resp));
</script>

Here's the code that makes up our ProductsApiController:

[ApiController]
[Route("api/[controller]")]
public class ProductsApiController : ControllerBase
{
    [HttpGet("{productId:int}")]
    public ActionResult GetProduct(int productId)
    {
        var culture = CultureInfo.CurrentCulture.Name;

        // ...
    }
}

Our original Razor View and HTML document were rendered using the Spanish language content and the URL this page is loaded from has the /es-MX path prefix.

When this GetProduct method is called from the XHR made by our JavaScript fetch() request, what will the value of culture be 🤔😕?

...

It's a trick question 🤦🏽‍♂️! I haven't told you what the default culture is for our site.

Since there's no culture code in the XHR request's URL, Xperience will associate it with whatever the default culture is for the site that the domain is associated with 😮.

In my specific use-case, it's English. This means that the culture variable will have the value en-US.

How can we get that to be es-MX so that any data we retrieve from the Xperience database and return from our API endpoint will be localized to the Page's culture 🤷🏼‍♀️?

🤝🏻🤝🤝🏾 Passing the Culture

There are many ways to pass the culture information in a URL and they would all work - really all we need to do is get the culture code to be a parameter (probably query string) that our GetProduct() method can directly access.

Then we can the CultureInfo constructor and the code pattern that Xperience already uses to set the culture on the current thread 👍🏾:

public ActionResult GetProduct(int productId, [FromQuery] string culture)
{
    var cultureInfo = CultureInfo.GetCultureInfo(culture);

    CultureInfo.CurrentCulture = cultureInfo;
    CultureInfo.CurrentUICulture = cultureInfo;

    // ...
}

The problem with this approach is we are now cluttering up our API action method with assigning the thread culture and we have this weird query string parameter we have to remember to include in all our other API requests and action methods.

We also don't have access to the correct culture until our Controller action method executes, which means Action filters and anything else that executes before the action are using our default culture 😣.

A better approach is to use the same feature that Xperience relies on for parsing out and assigning a culture to a Page's HTTP request.

We just need to make sure our API URL includes a special {culture} token in the route definition:

[ApiController]
[Route("api/{culture}/[controller]")] // <- new route token
public class ProductsApiController : ControllerBase
{
    [HttpGet("{productId:int}")]
    public ActionResult GetProduct(int productId)
    {
        var culture = CultureInfo.CurrentCulture.Name;

        // ^ culture will have the correct value now
    }
}

And, then include that in the fetch() request URL (we will source the culture value from CultureInfo.CurrentCulture.Name which is correctly set when rendering our Page):

<script>
    const productId = @Model.ProductId;
    const culture = '@CultureInfo.CurrentCulture.Name';

    fetch(`/api/${culture}/products/${productId}`)
        .then(resp => resp.json())
        .then(resp => console.log(resp));
</script>

I think this is a much nicer solution 👏🏽!

Our API URLs match the same culture path prefix pattern that our Page URLs have and we don't have to worry about extra culture related values and logic in our API action methods 👍🏼.

🧠 Conclusion

Globalization and localization are important features when they're needed, but they tend to create new problems that need solutions, especially if we're used to not worrying about other languages (like me!).

Kentico Xperience supports localization as a first class feature and, for the most part, handles it all for us 😉.

However, when we start to come up with clever technical solutions for our application requirements, we need to be sure to carry all the existing features forward.

Fortunately, culture-aware XHR requests can be enabled in an elegant and simple way with Kentico Xperience 13.0 sites.

As always, thanks for reading 🙏!

References

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico or Xperience tags here on DEV.

#kentico Follow

#xperience Follow

Or my Kentico Xperience blog series, like:

Kentico CMS Quick Tip: Using Font Awesome Icons for Custom Page Types

Sean G. Wright — Tue, 22 Sep 2020 14:30:06 +0000

Our Requirements

We want to give our Content Management team the ability to quickly identify the Custom Page Types we create for them, both in the Content Tree and when creating new Pages, using the huge Font Awesome 5 font icons set, integrated into Kentico Xperience.

TLDR; I created a .NET CLI global tool anyone can install, called Xperience Font Awesome Integrator, that will do all the hard work, described below, for you 🤗.

How Can We Assign Icons to Custom Page Types?

Kentico Xperience focuses most of the application's content management tasks on the Content Tree.

The items in this tree structure are identified by their position in the hierarchy, their name, and the icon that displays next to each of them.

We can change those icons for each Page Type by editing the settings in the Page Types module 👍🏾.

Existing Solution

Xperience provides us with a pre-defined set of icons we can use to help both developers and content editors identify Custom Page Types.

These icons are always used in the Dancing Goat demo application, and for good reason - they make it much easier to identify content types and content organization 🧐.

While the list of included icons is pretty nice, it's definitely been curated to be used with Xperience's demo sites and other visual elements in the Content Management application.

What if we can't find an appropriate icon in the list 🤔?

Our Solution - Use Font Awesome 5

We can follow the instructions in the Xperience docs that explain how to add custom font icons to the application.

The process requires the following steps:

Create the folder CMS\App_Themes\Default\Custom
Add a sub-folder that will contain the custom font files (ex: CMS\App_Themes\Default\Custom\fonts
Create a style.css file that contains the style rules to assign the font icons to DOM elements, taking into account the specificity requirements of the Content Management application
Create a icon-css-classes.txt manifest file which will populate the icon selector controls with our custom icons

Let's look at how we'd apply this steps for the (awesome 🤣) Font Awesome 5 icons!

Extract the Font Awesome Assets

Whether we download the Free icons or we have access to the Pro versions, we will end up with a .zip file which we can extract to a folder.

The extracted folders might be nested - we are interested in the one containing all the asset folders (\css, \js, ect...):

Copy the Webfonts folder to Xperience

We need the font files, that are used to display the icons, in our application.

This is easily accomplished by copying the \webfonts folder from the Font Awesome folder to CMS\App_Themes\Default\Custom 😉.

Convert the Metadata to a Manifest

Open the \metadata\icons.json file and take a look at the metadata for all icons included what we downloaded:

{
  "500px": {
    "changes": [...],
    "ligatures": [],
    "search": {
      "terms": []
    },
    "styles": [
      "brands"
    ],
    "unicode": "f26e",
    "label": "500px",
    "voted": false,
    "svg": {...},
    "free": [
      "brands"
    ]
  },
  { ... }
]

We are most interested in the keys of the top level object (ex: 500px) and the styles array of each of the child objects (ex: ["brands"]).

We want to convert each one of the keys and their styles to a line in the icon-css-classes.txt that we need to create.

We can now create our empty icon manifest file at CMS\App_Themes\Default\Custom\icon-css-classes.txt and start adding entries.

The example JSON above would result in 1 line:

fa fab-500px

If we scroll down the icons.json file and find the entry for address-book, we can see it is available in multiple styles (["solid", "regular"]). This means we should create a line in our icon-css-classes.txt for each style for this icon 🧐:

fa fab-500px
...
fa fas-address-book
fa far-address-book

We will need entries in our icon-css-classes.txt file for every icon we want available in the Xperience Content Management 😲.

Adapt the CSS File

The Font Awesome download comes with a set of .css files that define the style rules to use the icons in our application.

If we open up css\all.css we can see all the rules defined for the entire icon set:

/*!
 * Font Awesome Free 5.14.0 by @fontawesome - https://fontawesome.com
 * License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License)
 */
.fa,
.fas,
.far,
.fal,
.fad,
.fab {
  -moz-osx-font-smoothing: grayscale;
  -webkit-font-smoothing: antialiased;
  display: inline-block;
  font-style: normal;
  font-variant: normal;
  text-rendering: auto;
  line-height: 1; }

.fa-lg {
  font-size: 1.33333em;
  line-height: 0.75em;
  vertical-align: -.0667em; }

/* ... */

To ensure we override the specificity rules of the icon CSS included in Xperience, we need to modify the rules in .all.css to be more specific.

Let's copy all.css to CMS\App_Themes\Default\Custom\style.css and begin 📝 editing it.

First, we need to augment the selector for the general icon CSS rules:

.fa,.fas,.far,.fal,.fad,.fab,
.cms-bootstrap [class^='icon-'].fa,
.cms-bootstrap [class*=' icon-'].fa,
.cms-bootstrap [class^='icon-'].fab,
.cms-bootstrap [class*=' icon-'].fab,
.cms-bootstrap [class^='icon-'].fad,
.cms-bootstrap [class*=' icon-'].fad,
.cms-bootstrap [class^='icon-'].fal,
.cms-bootstrap [class*=' icon-'].fal,
.cms-bootstrap [class^='icon-'].far,
.cms-bootstrap [class*=' icon-'].far,
.cms-bootstrap [class^='icon-'].fas,
.cms-bootstrap [class*=' icon-'].fas {
  -moz-osx-font-smoothing: grayscale;
  -webkit-font-smoothing: antialiased;
  display: inline-block;
  /* ... */
}

Adding these additional selectors ensures that our Font Awesome icons use the correct CSS rules when displayed in the application 🙄.

We need to go through this file and replace each individual collection (Regular, Brand, Light, Solid, Duoton) selector with one that includes the CMS selectors.

Here is an example of the updated selector for Brand icons:

.fab,
.cms-bootstrap [class^='icon-'].fab,
.cms-bootstrap [class*=' icon-'].fab {
  /* ... */
}

Finally, we need to update the paths to the webfont files in the @font-face rules, which are slightly different when integrated into Xperience, changing url("../webfonts to url("./webfonts:

@font-face {
  font-family: 'Font Awesome 5 Brands';
  font-style: normal;
  font-weight: 400;
  font-display: block;
  src: url("./webfonts/fa-brands-400.eot");
  src: url("./webfonts/fa-brands-400.eot?#iefix") format("embedded-opentype"), url("./webfonts/fa-brands-400.woff2") format("woff2"), url("./webfonts/fa-brands-400.woff") format("woff"), url("./webfonts/fa-brands-400.ttf") format("truetype"), url("./webfonts/fa-brands-400.svg#fontawesome") format("svg"); }

Update our Project

The last step is to ensure all the new files we added to our application are included in the ASP.NET project, so that when we deploy our site, these files are deployed as well 😉.

Conclusion

When we run our application and navigate to the icon selector for a Custom Page Type, we can see the vastly enhanced list of icons available, which now included the entire set from Font Awesome 5!

If some of these steps seem confusing and you think creating a 1600 line long icon manifest file by hand (for the Free version) is a ridiculous idea (I know I do 🤪!), then fear not!

I created a .NET Core global tool called Xperience Font Awesome Integrator that does all this work for you and takes about 1 second to execute 🍻🎊🥳.

Running it from the command line looks like this:

> xperience-fa-integrator -fpath C:\dev\fontawesome-free-5.14.0-web -cpath C:\dev\Xperience\CMS

Pretty cool!

It works with both the Free and Pro versions of the Font Awesome 5 icons.

Give it a try and let me know what you think 👋🏼.

As always, thanks for reading 🙏!

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico tags here on DEV:

#xperience Follow

#kentico Follow

Or my Kentico Xperience blog series, like:

Kentico CMS Quick Tip: Azure Active Directory Authentication

Sean G. Wright — Mon, 20 Jul 2020 18:00:10 +0000

Our Requirements

Give our Content Management team a way to authenticate into Kentico CMS using their existing Azure Active Directory (AD) accounts and also keep individual account authentication.

Note: This article applies to Kentico 12. If you are using Kentico Xperience 13, please see the note at the end of the article to see how configuration is different in v13.

How Does the Built In Authentication Work?

Authenticating into the Kentico CMS content management application is a pretty simple process 😉:

Navigate to /Admin
Unauthenticated users are redirected to /CMSPages/logon.aspx
After entering a valid username and password, the application responds with an Authentication cookie.
Requests to the application check for this cookie when accessing routes requiring authentication.

This process relies on ASP.NET's Forms Authentication and all credentials are stored in the application's database.

Existing Solutions

If we want to integrate Azure AD into Kentico CMS for authentication, maybe we can use an existing open source solution or one blogged about by the Kentico CMS community 🧐!

Built-In Claims Based Authentication

First off, there is a solution that Kentico Xperience supports out of the box and it's detailed on Kentico's DevNet by a Kentico employee 👏🏽. Jeroen Furst, a fellow Kentico MVP 🤓, also detailed this process awhile ago on his blog.

However, this solution completely replaces Kentico Xperience's Forms Authentication with Azure AD authentication because "Mixed authentication mode of claims-based and forms authentication is also not supported." 😢.

This means all users of the application will need to have Azure AD accounts in the tenant specified by the App Registration in Azure AD.

As an agency, we want to use Azure AD for our authentication into our client's sites, but we also want to allow them to continue using Forms Authentication for their access. We definitely don't want to have all our clients accounts managed in our Azure AD tenant 😅!

Portal Engine Public Site Authentication

Kentico partner, Delete Agency, also has a solution up on GitHub.

This approach is much closer to what we want, as it augments rather than replaces the normal Forms Authentication 💪🏾.

However, the use-case is slightly different. This code provides authentication for Portal Engine based Kentico applications and the authentication is for live site users, not content management users 😣.

We want to follow the authentication steps that were detailed at the beginning of this post, but allow our employees to authenticate with Azure AD instead of application credentials.

Our Solution

Despite the fact that the Delete approach is for live site authentication, it follows the general outline of our approach 👍🏼.

Customizing the Logon Form

First, let's update the normal back end login form found in CMSApp/CMSPages/logon.aspx.

Replace the last <div> inside the <asp:Panel> (starting on line 100) with the following:



<div class="row" 
     style="display: flex; justify-content: space-between">

    <span>
        <cms:LocalizedButton ID="btnLogonAzureAD" 
            ButtonStyle="Primary" 
            CssClass="login-btn"
            Text="Logon With Azure AD" runat="server"
            OnClick="btnLogonAzureAD_Click" />
    </span>

    <span>
        <cms:LocalizedButton ID="LoginButton" 
            runat="server" 
            CommandName="Login" ValidationGroup="Login1"
            ButtonStyle="Primary" CssClass="login-btn" />
    </span>
</div>

All we did here was add a new button with the text "Logon With Azure AD" and some styles and markup to layout the buttons correctly.

Now let's add the C# in logon.aspx.cs to wire the button up:



protected void btnLogonAzureAD_Click(object sender, EventArgs e)
{
    // We will uncomment this line once we've created the
    // handler class

    // AzureADAuthenticationHandler.OnLogin(ReturnUrl);
}

Pretty easy 😅!

If we start up the content management application and navigate to /Admin (assuming we are not logged in), we will see this:

Creating a Custom `IHttpHandler`

Now we can create the handler class referenced in our logon.aspx.cs above:

If you are adding this directly the CMS code, you can create the class in Old_App_Code.



/// <summary>
/// Handles both the initial OAuth request to Azure AD and the redirect response
/// to authenticate the user into Kentico.
/// 
/// Operates according to the flow described here https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow
/// </summary>
public class AzureADAuthenticationHandler : IHttpHandler
{
    private static readonly string clientId;
    private static readonly string redirectUriPath;
    private static readonly string tenantId;
    private static readonly string clientSecret;
    private static readonly string groupClaimId;
    private static readonly string stateCookieName = "azure_ad_sso_state";

    public bool IsReusable => false;

    static AzureADAuthenticationHandler()
    {
        var settings = ConfigurationManager.AppSettings;

        clientId = settings["authentication:azure-ad:client-id"];
        redirectUriPath = settings["authentication:azure-ad:redirect-uri-path"];
        tenantId = settings["authentication:azure-ad:tenant-id"];
        clientSecret = settings["authentication:azure-ad:client-secret"];
        groupClaimId = settings["authentication:azure-ad:group-claim-id"];
    }

    // ...

}

First we read in a bunch of values from App Settings when the application starts up. These will all be populated from configuration in the Azure AD App Registration that we will create later 😎.

Now we will create the Logon method that will be called by logon.aspx.cs:



public static void OnLogin(string returnUrl)
{
    var uri = new UriBuilder($"https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize");

    /*
    * This state is both stored in a cookie and sent to the Azure AD authenticate URL
    * via query string.
    * 
    * When the redirect comes back after the Azure AD sign-in, we want to ensure
    * the request isn't an XSRF or replay attach so we pull the state values
    * out of the cookie and ensure they match what's in the query string.
    * 
    * The "ReturnUrl" captured by the Kentico login page allows us to send the user back
    * to their original destination if they were redirected to login for authentication.
    * 
    * After logging in we clear the state cookie.
    */
    var state = new OIDCState { ReturnUrl = returnUrl, Id = Guid.NewGuid().ToString() };

    string encodedState = Base64Encode(JsonConvert.SerializeObject(state));

    var parameters = HttpUtility.ParseQueryString(string.Empty);
    parameters.Add(new NameValueCollection
    {
        ["client_id"] = clientId,
        ["response_type"] = "code",
        ["response_mode"] = "query",
        // We request the 'profile' scope to get access to the user's Azure AD groups
        // to ensure they are allowed to SSO into Kentico
        // https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-optional-claims#configuring-groups-optional-claims
        ["scope"] = "openid profile",
        ["redirect_uri"] = $"{HttpContext.Current.Request.Url.GetLeftPart(UriPartial.Authority)}{redirectUriPath}",
        ["state"] = encodedState
    });

    uri.Query = parameters.ToString();

    /*
    * We can't use CookieHelper.SetValue() because it requires an expiration
    * date and Chrome won't process the set-cookie header on 302 responses
    * when an Expires cookie value is set
    * https://bugs.chromium.org/p/chromium/issues/detail?id=696204
    * 
    * This problem does not appear in localhost requests or in other browsers
    */
    HttpContext.Current.Response.AppendCookie(new HttpCookie(stateCookieName)
    {
        HttpOnly = true,
        Value = encodedState,
        SameSite = SameSiteMode.Lax,
        Secure = true,
        Path = "/",
        Domain = HttpContext.Current.Request.Url.Host
    });

    HttpContext.Current.Response.Redirect(uri.ToString());
}

This code creates a security cookie / state value to protect against XSRF attacks 😮 and also generates a redirect request to Azure AD to ensure the user is authenticated there.

We now create an Authenticate() method that handles the request back to our application, redirected from Azure AD after the user is authenticated there:



private (bool isAuthenticated, string redirectUrl) Authenticate(HttpContext context)
{
    if (AuthenticationHelper.IsAuthenticated())
    {
        return (false, "");
    }

    var query = context.Request.QueryString;

    string code = query.Get("code");
    string encodedRequestState = query.Get("state");
    string encodedCookieState = CookieHelper.GetValue(stateCookieName);

    if (string.IsNullOrWhiteSpace(code) ||
        string.IsNullOrWhiteSpace(encodedRequestState) ||
        string.IsNullOrWhiteSpace(encodedCookieState))
    {
        return (false, "");
    }

    var requeststate = JsonConvert.DeserializeObject<OIDCState>(Base64Decode(encodedRequestState));
    var cookiestate = JsonConvert.DeserializeObject<OIDCState>(Base64Decode(encodedCookieState));

    if (!string.Equals(requeststate.Id, cookiestate.Id, StringComparison.OrdinalIgnoreCase))
    {
        return (false, "");
    }

    string uri = $"https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token";

    var parameters = new NameValueCollection
    {
        ["client_id"] = clientId,
        ["scope"] = "openid profile",
        ["code"] = code,
        ["redirect_uri"] = $"{HttpContext.Current.Request.Url.GetLeftPart(UriPartial.Authority)}{redirectUriPath}",
        ["grant_type"] = "authorization_code",
        ["client_secret"] = clientSecret
    };

    string responseString = "";

    using (var client = new WebClient())
    {
        try
        {
            byte[] response = client.UploadValues(uri, "POST", parameters);

            responseString = Encoding.Default.GetString(response);
        }
        catch (Exception ex)
        {
            EventLogProvider.LogException(nameof(AzureADAuthenticationHandler), "AUTH_FAILURE", ex);

            return (false, "");
        }
    }

    if (string.IsNullOrWhiteSpace(responseString))
    {
        return (false, "");
    }

    var resp = JsonConvert.DeserializeObject<OIDCResponse>(responseString);

    if (string.IsNullOrWhiteSpace(resp.AccessToken))
    {
        return (false, "");
    }

    var handler = new JwtSecurityTokenHandler();

    /*
    * Here are the claims available in each token type
    * https://docs.microsoft.com/en-us/azure/active-directory/develop/id-tokens
    * https://docs.microsoft.com/en-us/azure/active-directory/develop/access-tokens
    * 
    * The difference between the token types is important when using them to access
    * APIs on behalf of the user, but we only use them for their payload data.
    */
    var accessToken = handler.ReadJwtToken(resp.AccessToken);
    var idToken = handler.ReadJwtToken(resp.IdToken);

    if (!idToken.Claims.Any(c => c.Type == "groups" && string.Equals(c.Value, groupClaimId, StringComparison.OrdinalIgnoreCase)))
    {
        return (false, "");
    }

    string upn = GetClaimValue(accessToken, "upn", null);
    string email = GetClaimValue(accessToken, "email", null);

    /*
    * Guest accounts (invited from another Azure AD tenant/domain) don't expose the 'upn' claim
    * so we have to get the username/email from the 'email' claim
    */
    string identifier = upn ?? email ?? "";

    if (string.IsNullOrWhiteSpace(identifier))
    {
        return (false, "");
    }

    var user = UserInfoProvider.GetUserInfo(identifier);

    if (user is null)
    {
        user = new UserInfo
        {
            IsExternal = true,
            UserName = identifier,
            Email = identifier,
            FirstName = GetClaimValue(accessToken, "given_name"),
            LastName = GetClaimValue(accessToken, "family_name"),
            Enabled = true,
            FullName = GetClaimValue(accessToken, "name"),
            SiteIndependentPrivilegeLevel = UserPrivilegeLevelEnum.GlobalAdmin
        };

        UserInfoProvider.SetUserInfo(user);
        UserInfoProvider.AddUserToSite(user.UserName, SiteContext.CurrentSiteName);
        UserInfoProvider.AddUserToRole(user.UserID, 3);
    }

    AuthenticationHelper.AuthenticateUser(identifier, true);
    CookieHelper.Remove(stateCookieName);

    if (string.IsNullOrWhiteSpace(requeststate.ReturnUrl))
    {
        return (true, "/Admin");
    }

    return (true, requeststate.ReturnUrl);
}

To get all the compilation errors to go away we need a couple utility methods and classes:



private static string Base64Encode(string value)
{
    byte[] valueBytes = Encoding.UTF8.GetBytes(value);
    return Convert.ToBase64String(valueBytes);
}

private static string Base64Decode(string value)
{
    byte[] valueBytes = Convert.FromBase64String(value);
    return Encoding.UTF8.GetString(valueBytes);
}

private static string GetClaimValue(JwtSecurityToken token, string claimType, string defaultValue = "") =>
    token.Claims
      .FirstOrDefault(c => 
          c.Type.Equals(claimType, StringComparison.OrdinalIgnoreCase))
      ?.Value ?? defaultValue;

// ...

internal class OIDCState
{
    public string ReturnUrl { get; set; }
    public string Id { get; set; }
}

internal class OIDCResponse
{
    [JsonProperty("access_token")]
    public string AccessToken { get; set; }
    [JsonProperty("token_type")]
    public string TokenType { get; set; }
    [JsonProperty("expires")]
    public long Expires { get; set; }
    [JsonProperty("scope")]
    public string Scope { get; set; }
    [JsonProperty("refresh_token")]
    public string RefreshToken { get; set; }
    [JsonProperty("id_token")]
    public string IdToken { get; set; }
}

We also need to install a NuGet package, System.IdentityModel.Tokens.Jwt, to help us parse the Jwt that comes back from Azure AD when we request it to verify the token sent to us in the URL query string.

Finally, we need to implement IHttpHandler and add a ProcessRequest() method:



public void ProcessRequest(HttpContext context)
{
    var (isAuthenticated, returnUrl) = Authenticate(context);

    if (!isAuthenticated)
    {
        EventLogProvider.LogEvent("I", "Azure AD Authentication", "AUTHENTICATIONFAIL", $"Could not log in user");
    }
    else
    {
        EventLogProvider.LogEvent("I", "Azure AD Authentication", "AUTHENTICATIONSUCCESS", $"Authentication success");
    }

    URLHelper.LocalRedirect(returnUrl);
}

We can now go back to logon.aspx.cs and comment the line AzureADAuthenticationHandler.OnLogin(ReturnUrl); 👍🏻.

Adding the Handler to the `web.config`

We want our handler to handle any requests matching a specific URL pattern, which in following OIDC authentication conventions will be /oidc-callback.

Since our handler class inherits from IHttpHandler, ASP.NET will pass it requests matching a pattern by registering it in the application web.config correctly:



<system.webServer>
  <!-- ... -->

  <handlers>
    <!-- ... -->

    <add name="AzureADOIDCCallback" 
         path="oidc-callback" verb="GET" 
        type="Namespace.AzureADAuthenticationHandler, CMSApp"
        preCondition="integratedMode,runtimeVersionv4.0" />
  </handlers>

In the above code, Namespace.AzureADAuthenticationHandler should be the namespace of your AzureADAuthenticationHandler class and CMSApp should be the name of the assembly your class is located in.

Creating an Application Registration in Azure

Now we can create a new App Registration in Azure AD.

Navigate to https://portal.azure.com, open the Azure AD blade (or search for Azure AD in the search bar), select "App Registrations" from the left side menu, and click "+ New Registration" at the top-left of the screen.

Now, fill in the details, giving it a friendly name and specifying the full Redirect URI with the path matching what we defined in the web.config for the handler (eg: https://localhost:44332/oidc-callback):

Next, collect the identifiers from the "Overview" blade accessed from the left side menu. We want the "Application (client) ID" and "Directory (tenant) ID":

This implementation restricts authentication to users that are in a specific Azure AD group, but to get access to a user's groups, we need to add an "Optional claim" by selecting the "Token configuration" option from the left menu 🧐.

Select "+ Add groups claim" and check "Security groups" and save:

The last step for the App Registration is to create a client secret that the Kentico application can use to verify the OIDC callback token and get the ID and Access tokens from the Azure AD API.

Select "Certificates & secrets" from the left side menu and click "+ New client secret":

We have to make sure we copy the client secret and save it as we won't be able to see it again later 😏.

Finally, create an Azure AD Group and assign some users to it - only users in this group will be allowed to use the Azure AD SSO functionality in Kentico. Copy its "Object Id" from the Groups list and save this for our App Settings.

Adding Our Application Settings

Now we only need to configure the application settings by copying the values from eariler.

tenant-id from the App Registration Overview
client-id from the App Registration Overview
redirect-uri-path matches the web.config path for the handler
client-secret from the client secret we created in the "Certificats & secrets" blade
group-claim-id from the "Object Id" in the Azure AD Groups blade



  <add key="authentication:azure-ad:tenant-id" value=""/>
  <add key="authentication:azure-ad:client-id" value=""/>
  <add key="authentication:azure-ad:redirect-uri-path" value="/oidc-callback"/>
  <add key="authentication:azure-ad:client-secret" value=""/>
  <add key="authentication:azure-ad:group-claim-id" value=""/>

The only other setting we need is to tell Kentico to ignore the /oidc-callback path and not try to match it up with a path handled by the content management application URL processing used in Portal Engine sites 😉.

Log into the content management app, and navigate to the Settings module. Click "URLs and SEO", scroll to "URL format", find the Excluded URLs setting and add /oidc-callback.

Kentico Xperience 13 configuration

If you are using Kentico Xperience 13, you'll notice that the "Excluded URLs" field in the Settings module no longer exists. There is a "Excluded Alternative URLs" field, but this configures the live site ASP.NET Core application, not the CMS administration application.

To hook into the request pipeline and tell Xperience to ignore handling requests starting with /oidc-callback, you can add this custom module to your CMSApp project.



   [assembly: RegisterModule(typeof(AzureADAuthenticationRoutingModule))]

   namespace AppCodeName.Management.Web.Authentication
   {
       public class AzureADAuthenticationRoutingModule 
           : Module
       {
           public AzureADAuthenticationRoutingModule() 
               : base(nameof(AzureADAuthenticationRoutingModule))
           {
               var appSettings = ConfigurationManager.AppSettings;

               string redirectUriPath = appSettings["authentication:azure-ad:redirect-uri-path"];

               URLRewritingEvents.ProcessRewritingResult.Before += (s, e) =>
               {
                   if (e.Parameters.RelativePath.StartsWith(redirectUriPath, StringComparison.OrdinalIgnoreCase))
                   {
                       e.Cancel();
                   }
               };
           }
       }
   }

This code tells the administration application to not try to handle (rewrite) requests starting with whatever value is stored in our authentication:azure-ad:redirect-uri-path web.config key. In this post's example, that would be /oidc-callback.

Conclusion

Our Azure AD SSO integration is complete. We can now go to the login page of the content management app and click the "Logon With Azure AD", go through the OAuth redirection flow, and be logged straight into the application without having to supply any credentials 🎉🎉🥳.

In addition to the above workflow, new users in our Azure AD tenant that don't already have accounts in Kentico, will have accounts automatically created for them during sign-in.

The above code sets all SSO users as Global Administrators 🤠 when new accounts are being created, but we could instead add Azure AD Groups as Kentico Roles and then ensure the Roles of the authenticating user inside Kentico matched the Azure AD Groups.

If you run into any issues setting this up, leave a comment below and we'll figure it out. There's a lot of separate steps here and some tricky configuration.

This Azure AD authentication integration has worked great for us at WiredViews, reducing the complexity and tedium of user management across all our Kentico applications. I hope others find it useful as well.

As always, thanks for reading 🙏!

Photo by Gabriel Wasylko on Unsplash

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico tags here on DEV:

#kentico Follow

#kontent Follow

Or my Kentico Xperience blog series:

Kentico CMS Quick Tip: Creating an Email Whitelist For Testing Kentico EMS

Sean G. Wright — Mon, 13 Apr 2020 13:47:54 +0000

Our Requirements

Imagine we need to configure Kentico for testing and we have real customer or user data in the database.

We need to allow for testers and stakeholders to fully test the system - this means when they perform operations that would send emails, those emails should be sent 👍🏾!

However, we can't allow emails to be sent out to those real users from our testing environment 😨.

Telling everyone "Don't click this button because that could send out an email to a non-test user" isn't a great solution 🙁.

We need a way to whitelist a set of addresses or domains to receive emails, and intercept attempts to send emails to all others 🤔.

First, we need to identify all features in Kentico EMS that could result in emails being sent...

What Features in Kentico EMS Send Emails?

Kentico uses its email system to support a lot of functionality within the application. This includes:

... and more ...

That's a lot of different email configuration to manage!

So, it's unlikely that we'll be able to customize all these parts of the application to whitelist emails 😒.

Maybe there's a single, central service that Kentico uses to send emails where we could make our customizations?

CMS.EmailEngine.EmailProvider

Fortunately for us, Kentico exposes a Provider class that does exactly what we need!

Looking through the Kentico EMS documentation we can find information about the CMS.EmailEngine.EmailProvider class 💪🏾.

The documentation states:

Customizing the email provider allows you to:

Execute custom actions when sending emails (for example logging the sent emails for auditing purposes)

Use third‑party components for sending emails

Once you create and register your custom email provider, it is used to process all emails sent out by Kentico.

Perfect!

The EmailProvider class exposes (3) protected methods we can override, however we only need to focus on (2) of them:

/// <summary>
/// Synchronously sends an email through the SMTP server.
/// </summary>
protected override void SendEmailInternal(
    string siteName, MailMessage message, SMTPServerInfo smtpServer)

/// <summary>
/// Asynchronously sends an email through the SMTP server.
/// </summary>
protected override void SendEmailAsyncInternal(
    string siteName, MailMessage message, 
    SMTPServerInfo smtpServer, EmailToken emailToken)

Creating Our `WhitelistEmailProvider`

To override and intercept Kentico's email processing, we need to create our sub-class and register it as a custom provider:

// ✅ Don't forget this attribute
[assembly: RegisterCustomProvider(typeof(WhitelistEmailProvider))]

namespace Sandbox.Infrastructure.Emails
{
    public class WhitelistEmailProvider: EmailProvider
    {
        protected override void SendEmailAsyncInternal(
            string siteName, MailMessage message, 
            SMTPServerInfo smtpServer, EmailToken emailToken)
        {
            // ... insert custom functionality

            base.SendEmailAsyncInternal(
                siteName, message, smtpServer, emailToken);
        }

        protected override void SendEmailInternal(
            string siteName, MailMessage message, SMTPServerInfo smtpServer)
        {
            ... insert custom functionality

            base.SendEmailInternal(siteName, message, smtpServer);
        }
    }
}

We still call the parent class methods (base.SendEmailInternal()) because we don't want to write all the email processing logic - just a small part.

Configuring an Email Whitelist

Now that we have a spot in our code base to whitelist and intercept outgoing emails, we need to decide how we are actually going to do that whitelisting.

Let's use Kentico's support for Custom Settings to define a place where site administrators can update the email whitelist settings 🙂.

Take a look at Kentico's documentation on Creating custom modules for more information on what Custom Modules are and how they work.

In the screenshot below you can see I've created a Custom Module named Sandbox and I'm about to modify the Settings -> System -> Emails node from within this module:

I enter some values for a "New settings group":

And then I create several "New settings key" entries:

Setting 1:

Display Name: Is Whitelisting Enabled
Code name: SANDBOX_EMAIL_WHITELIST_IS_WHITELIST_ENABLED
Description: Check to enable email whitelisting
Type: Boolean
Editing control: Default

Setting 2:

Display Name: Whitelisted Emails
Code name: SANDBOX_EMAIL_WHITELIST_WHITELISTED_EMAILS
Description: Domain suffixes or specific email addresses, semi-colon delimited that will be whitelisted from email interception
Type: Text
Editing control: Form Control -> Text area

Setting 3:

Display Name: Intercepting Email Address
Code name: SANDBOX_EMAIL_WHITELIST_INTERCEPTING_ADDRESS
Description: When email whitelisting is enabled, any non-whitelisted emails will be send to this address instead of the intended recipients
Type: Text
Editing control: Default

Our resulting UI for these custom settings should look like the following screenshot:

Creating `EmailWhitelistSettings`

Now that we have a place to store our settings for email whitelisting and a custom class to override email sending functionality, we can add our custom code.

First, let's create a EmailWhitelistSettings class to abstract out our custom settings.

We create a nested class to hold our settings keys. By using the nameof() operator, I get the string value of the key to match the key name automatically 🤓:

public static class EmailWhitelistSettings
{
    public static class SettingKeys
    {
        public const string SANDBOX_EMAIL_WHITELIST_IS_WHITELIST_ENABLED = 
            nameof(SANDBOX_EMAIL_WHITELIST_IS_WHITELIST_ENABLED);
        public const string SANDBOX_EMAIL_WHITELIST_WHITELISTED_EMAILS = 
            nameof(SANDBOX_EMAIL_WHITELIST_WHITELISTED_EMAILS);
        public const string SANDBOX_EMAIL_WHITELIST_INTERCEPTING_ADDRESS = 
            nameof(SANDBOX_EMAIL_WHITELIST_INTERCEPTING_ADDRESS);
    }

We make (2) private fields to hold some default values:

private static readonly string fallbackWhitelist = 
    "<YOUR FALLBACK WHITELIST>";
private static readonly string fallbackInterceptingAddress = 
    "<YOUR FALLBACK INTERCEPTING ADDRESS>";

Now we make several static methods to retrieve the values from settings:

public static IEnumerable<string> WhitelistedRecipients()
{
    string whitelistedRecipients = SettingsKeyInfoProvider.GetValue(
        SettingKeys.SANDBOX_EMAIL_WHITELIST_WHITELISTED_EMAILS);

    if (IsDebug())
    {
        whitelistedRecipients = string.IsNullOrWhiteSpace(whitelistedRecipients)
            ? fallbackWhitelist
            : whitelistedRecipients;
    }

    return (whitelistedRecipients ?? "")
        .Split(';')
        .Select(r => r.Trim());
}

public static string InterceptingAddress()
{
    string interceptingAddress = SettingsKeyInfoProvider.GetValue(
        SettingKeys.ZEL01_EMAIL_WHITELIST_INTERCEPTING_ADDRESS);

    if (IsDebug())
    {
        interceptingAddress = string.IsNullOrWhiteSpace(interceptingAddress)
            ? fallbackInterceptingAddress
            : interceptingAddress;
    }

    return interceptingAddress;
}

public static bool IsWhitelistEnabled =>
    IsDebug()
        ? true
        : SettingsKeyInfoProvider.GetBoolValue(
              SettingKeys.ZEL01_IS_EMAIL_WHITELIST_ENABLED);

What about that IsDebug() method?

private static bool IsDebug()
{
    bool isDebug = false;
#if DEBUG
    isDebug = true;
#endif
    return isDebug;
}

We can see here, that I use a pre-processor directive to ensure that if I'm doing a DEBUG build (running the site locally), I'm guaranteed to have whitelisting (and fallbacks) enabled.

This prevents me from accidentally running some code locally that sends out emails to real users 😏!

We could also use a local email server for this (like hMailServer, MailSlurper, or Papercut but a code level check is double-safe!

Finally, we add a utility method to determine if a given email address has been whitelisted:

public bool IsWhitelistedRecipient(string recipient) =>
    whitelistedEmails.Any(e => e.StartsWith("@")
        ? recipient.EndsWith(e, StringComparison.OrdinalIgnoreCase)
        : string.Equals(recipient, e, StringComparison.OrdinalIgnoreCase));

This method will match on full address or a domain suffix. For example, if the following are whitelisted, "test@test.com;@wiredviews.com", all of my co-workers could receive emails normally, along with "test@test.com". All other addresses are going to be captured and re-routed 🧐.

Customizing the `WhitelistEmailProvider`

Ok! We're finally ready to custom the WhitelistEmailProvider.

I'm only going to show the SendEmailInternal method, since the other will be implemented the same way.

The override is pretty simple because all the functionality is going to be in a ProcessEmail method:

private override void SendEmailInternal(
    string siteName, MailMessage message, SMTPServerInfo smtpServer)
{
    base.SendEmailInternal(siteName, ProcessEmail(message), smtpServer);
}

We can see in ProcessEmail that determines if the email should be handled or directly returned:

protected MailMessage ProcessEmail(MailMessage message) =>
    EmailWhitelistSettings.IsWhitelistEnabled && !IsWhitelisted(message)
        ? ModifyMessage(message)
        : message;

We use the IsWhitelisted(MailMessage message) method to determine if the given message has any non-whitelisted email addresses in all of its sending fields (To, CC, Bcc):

private bool IsWhitelisted(MailMessage message)
{
    var whitelisted = EmailWhitelistSettings.WhitelistedRecipients();

    return message.To.All(a => EmailWhitelistSettings
            .IsWhitelistedRecipient(a.Address, whitelisted))
        && message.CC.All(a => EmailWhitelistSettings
            .IsWhitelistedRecipient(a.Address, whitelisted))
        && message.Bcc.All(a => EmailWhitelistSettings
            .IsWhitelistedRecipient(a.Address, whitelisted));
}

Finally we have a larger method, ModifyMessage(MailMessage message), which is called when the recipients of the email are not whitelisted.

In this method we want to change the recipients to use the intercepting address, and record the original recipients at the bottom of the email's body:

/// <summary>
/// Replaces the recipients fields with intercepting email address and appends
/// the original recipients to the end of the email
/// </summary>
/// <param name="message"></param>
/// <returns></returns>
private MailMessage ModifyMessage(MailMessage message)
{
    // ✅ Grab all the original recipients
    var originalTo = message.To.Select(e => e.Address).ToList();
    var originalCc = message.CC.Select(e => e.Address).ToList();
    var originalBcc = message.Bcc.Select(e => e.Address).ToList();

    // ✅ Now clear them out
    message.To.Clear();
    message.CC.Clear();
    message.Bcc.Clear();

    // ✅ Add our intercepting address as the only recipient
    message.To.Add(
        new MailAddress(EmailWhitelistSettings.InterceptingAddress()));

    // ✅ Indicate in the subject this email has been overriden
    message.Subject = $"{message.Subject}: override";

    // ✅ Find the HTML email (ignore plain text for now)
    var nullableView = message
        .AlternateViews
        .FirstOrDefault(m => 
            m.ContentType.MediaType == MediaTypeNames.Text.Html);

    if (!(nullableView is AlternateView view))
    {
        return message;
    }

    // ✅ Remove the existing HTML content from the email
    message.AlternateViews.Remove(view);

    var builder = new StringBuilder();

    string template = "<p>{0}</p>";

    // ✅ Read out the HTML content as a string
    using (var reader = new StreamReader(view.ContentStream))
    {
        string originalContents = reader.ReadToEnd();

        builder.Append(originalContents);
    }

    // ✅ Create all the override information
    builder.AppendFormat(template, $"--- Email Override ---");
    builder.AppendFormat(template, 
        $"original to: {string.Join(", ", originalTo.ToList())}");

    if (originalCc.Any())
    {
        builder.AppendFormat(template, 
            $"original cc: {string.Join(", ", originalCc.ToList())}");
    }

    if (originalBcc.Any())
    {
        builder.AppendFormat(template, 
            $"original bcc: {string.Join(", ", originalBcc.ToList())}");
    }

    string updatedBody = builder.ToString();

    var originalContentType = new ContentType(MediaTypeNames.Text.Html));

    // ✅ Create new HTML content and attach it to the email
    string newView = AlternateView
        .CreateAlternateViewFromString(updatedBody, originalContentType);

    message.AlternateViews.Add(newView);

    return message;
}

The AlternateView that makes up the content of the MailMessage is not editable 😕, so we instead have to remove it from the MailMessage, read its content as a string and append our override messages to it.

We then create a new AlternateView that has our updated content as the email body, and add it to the MailMessage.

There's definitely some extra processing going on here that you don't want to run during production while sending out bulk emails. However, that's definitely not a scenario for this email whitelisting 😋.

Assuming our settings are correctly configured in the CMS and the custom provider is registered with Kentico (by using the assembly attribute), when our application attempts to send emails, they will be checked by the whitelisting process and either re-routed or sent out correctly 😄!

Conclusion

As we develop our Kentico applications we might find the need to test parts of the system that will send out emails using Kentico's underlying email processing.

If we have any real email addresses in the database, we run the risk of emails being sent to users from non-production sites 😦.

We could use SMTP servers that capture emails, but that might not allow testers and stakeholders to verify the functionality of the site as it would be in a production scenario. It also adds another tool that testers would need to have access to while testing common workflows 😔.

Instead, we can leverage Kentico's robust overriding/intercepting patterns of its internal providers 😅.

By designing an email "whitelist" feature, we can enable email whitelisting for testers and stakeholders while still intercepting and re-routing emails destined for real, non-test addresses.

Kentico's custom settings functionality allows site administrators easy access to these settings within the CMS, which is great for enabling new domains or email addresses as the testing phase of a site proceeds 👏🏾.

Finally, once the site is ready to go live, we can either disable whitelisting in the CMS settings, remove the custom provider attribute to un-register it in Kentico or delete the class entirely, at which point email processing by the CMS will return to normal.

Pretty cool 😎.

As always, thanks for reading 🙏!

Photo by Joanna Kosinska on Unsplash

We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico tag here on DEV:

#kentico Follow

Or my Kentico blog series:

Kentico CMS Quick Tip: Understanding E-Commerce XML Structures

Sean G. Wright — Mon, 18 Nov 2019 14:40:07 +0000

Photo by Ramiro Mendes on Unsplash

E-Commerce Types and XML Data

Kentico's documentation provides examples of ways that developers can interact with the OrderInfo and OrderItemInfo types 👍.

These are the primary objects developers retrieve order information from after a customer completes checkout with their shopping cart and an OrderInfo instance is created from the ShoppingCartInfo instance belonging to the customer.

However, it's not so clear from the documentation how all the fields in these objects get populated and what values we should expected to be stored in them 🤷🏽‍♀️.

This is especially true with the XML structures that Kentico uses for Summary and Custom Data fields, which we might find ourselves needing to parse for business logic customizations 🤨.

Below, we'll look at where these XML values come from and what schema we should expect them to use 🤓.

OrderInfo fields

OrderCustomData

How do we populate it?

This is one of a couple fields that is transparently copied from the ShoppingCartInfo to the OrderInfo when the order is created, so we can use either the ShoppingCartInfo.ShoppingCartCustomData or OrderInfo.OrderCustomData.

// Via the ShoppingCartInfo
var shoppingService = Service.Resolve<IShoppingService>();

ShoppingCartInfo cart = shoppingService.GetCurrentShoppingCart();

cart.ShoppingCartCustomData.SetValue("CustomDataNumber", 42);
cart.ShoppingCartCustomData.SetValue("CustomDataString", "Hello");

cart.Update();

// Via the OrderInfo
OrderInfo order = OrderInfoProvider.GetOrderInfo(23);

order.OrderCustomData.SetValue("CustomDataNubmer", 42);
order.OrderCustomData.SetValue("CustomDataString", "Hello");

order.Update();

Where is it stored in the db?

COM_Order.OrderCustomData

What will it look like?

<CustomData>
    <CustomDataNumber>42</CustomDataNumber>
    <CustomDataString>Hello</CustomDataString>
</CustomData>

OrderPaymentResult

How do we populate it?

To set a payment result on an order we need to use the OrderInfo.UpdateOrderStatus() method, passing a valid PaymentResultInfo.

var paymentResult = new PaymentResultInfo
{
    PaymentDate = DateTime.Now,
    PaymentDescription = "Test Payment completed",
    PaymentIsCompleted = true,
    PaymentIsAuthorized = true,
    PaymentTransactionID = Guid.NewGuid().ToString(),
    PaymentStatusValue = Guid.NewGuid().ToString(),
    PaymentMethodName = "TestPaymentName"
};

OrderInfo order = OrderInfoProvider.GetOrderInfo(23);

order.UpdateOrderStatus(paymentResult);

order.Update();

We can see below that each value populated in the PaymentResultInfo creates an element in the XML stored in the database.

The values like {$PaymentGateway.Result.TransactionID$} are unresolved localization macros that would be populated with translated values of the specific payment gateway / payment method being used for this order 🧐.

However, in my examples I have not populated those localization strings.

Where is it stored in the db?

COM_Order.OrderPaymentResult

What will it look like?

<result>
    <item name="date" 
        header="{$PaymentGateway.Result.Date$}" 
        value="11/17/2019 10:16:30 PM" />
    <item name="method" 
        header="{$PaymentGateway.Result.PaymentMethod$}" 
        text="TestPaymentName" />
    <item name="status" 
        header="{$PaymentGateway.Result.Status$}" 
        value="6a418f48-2aee-4bde-86ef-c6e3eef6667e" />
    <item name="transactionid" 
        header="{$PaymentGateway.Result.TransactionID$}" 
        value="237b5af1-bc28-4187-b9d4-0ecf1084b6ec" />
    <item name="description" 
        header="{$PaymentGateway.Result.Description$}" 
        value="Test Payment completed" />
    <item name="completed" 
        header="{$PaymentGateway.Result.IsCompleted$}" 
        value="1" text="{$PaymentGateway.Result.PaymentCompleted$}" />
    <item name="authorized" 
        header="{$PaymentGateway.Result.IsAuthorized$}" 
        value="1" text="{$paymentgateway.result.paymentauthorized$}" />
    <item name="failed" header="{$PaymentGateway.Result.IsFailed$}" />
</result>

OrderDiscounts

How do we populate it?

Order discounts come from coupon codes defined in the CMS under the "Order Discounts" module.

In the example below I've created an Order Discount named Test Discount 10% that applies a 10% discount to the entire order.

Then I created a Coupon Code, TEST_10_OFF, for this discount.

var shoppingService = Service.Resolve<IShoppingService>();

shoppingService.AddCouponCode("TEST_10_OFF");

Where is it stored in the db?

COM_Order.OrderDiscounts

What will it look like?

<Summary>
    <Item>
        <Name>Test Discount 10%</Name>
        <Value>0.30</Value>
    </Item>
</Summary>

OrderOtherPayments

How do we populate it?

This field stores gift cards applied to the order, and in Kentico gift cards are basically coupons that reduce the final cost of the entire order and also the total balance of the gift card.

So, it shouldn't be much of a surprise that gift cards are added to an order the same way coupon codes are 😀.

For the example below, in the CMS "Gift Cards" module, I created a gift card named "Two Dollar Gift Card" with a coupon code TWO_DOLLARS_PLEASE.

var shoppingService = Service.Resolve<IShoppingService>();

shoppingService.AddCouponCode("TWO_DOLLARS_PLEASE");

Where is it stored in the db?

COM_Order.OrderOtherPayments

What will it look like?

<Summary>
    <Item>
        <Name>Two Dollar Gift Card</Name>
        <Value>2.00</Value>
    </Item>
</Summary>

OrderTaxSummary

How do we populate it?

Taxes for an order are calculated by an ITaxCalculationService which has a pretty simple signature, TaxCalculationResult CalculateTaxes(TaxCalculationRequest taxRequest).

Kentico's documentation has a good example of how an implementation of this interface might look 💪🏿.

Here's a trivial example of an ITaxCalculationService that sets some values in the TaxCalculationResult.Summary.

public class CustomTaxCalculationService : ITaxCalculationService
{
    public TaxCalculationResult CalculateTaxes(
        TaxCalculationRequest taxRequest)
    {
        var result = new TaxCalculationResult();

        decimal itemsTotal = ...

        result.ItemsTax = itemsTotal * .01m;

        result.Summary.Sum("Custom tax", itemsTotal * .027m);

        decimal shippingTaxRate = 0.15m;
        result.ShippingTax = taxRequest.ShippingPrice * shippingTaxRate;

        result.Summary.Sum("Custom shipping tax", result.ShippingTax);

        result.Summary.Sum("County Tax", itemsTotal * .06m);

        return result;
    }
}

We can see below how each of the string keys used in our call to Summary.Sum() (like "County Tax") results in a element in the XML summary.

Where is it stored in the db?

COM_Order.OrderTaxSummary

What will it look like?

<Summary>
    <Item>
        <Name>Custom tax</Name>
        <Value>0.270</Value>
    </Item>
    <Item>
        <Name>Custom shipping tax</Name>
        <Value>0.000</Value>
    </Item>
    <Item>
        <Name>County Tax</Name>
        <Value>0.1620</Value>
    </Item>
</Summary>

OrderCouponCodes

How do we populate it?

By applying any coupons to an order we can populate the OrderCouponCodes field - this include both order discount coupons and gift card coupons.

These are the coupons that result in the OrderOtherPayments and OrderDiscounts fields being populated 🧐.

This field will also contain any "Product Coupons" (see OrderItemDiscountSummary below) applied to the order, even though these are order item specific.

var shoppingService = Service.Resolve<IShoppingService>();

// Apply an order discount
shoppingService.AddCouponCode("TEST_10_OFF");

// Apply a gift card
shoppingService.AddCouponCode("TWO_DOLLARS_PLEASE");

Where is it stored in the db?

COM_Order.OrderCouponCodes

What will it look like?

<CouponCodes>
    <CouponCode>
        <Code>TEST_10_OFF</Code>
    </CouponCode>
    <CouponCode>
        <Code>TWO_DOLLARS_PLEASE</Code>
        <ValueInMainCurrency>2.00</ValueInMainCurrency>
    </CouponCode>
</CouponCodes>

OrderItem fields

OrderItemCustomData

How do we populate it?

This field works just like OrderInfo.OrderCustomData, except it allows us to store custom data per line-item in the order. This means we can use either ShoppingCartItemInfo.CartItemCustomData or OrderItemInfo.OrderItemCustomData.

// Via the ShoppingCartItemInfo
var shoppingService = Service.Resolve<IShoppingService>();

ShoppingCartInfo cart = shoppingService.GetCurrentShoppingCart();

ShoppingCartItemInfo cartItem = cart.CartItems.First();

cartItem.CartItemCustomData.SetValue("CustomDataNumber", 10);
cartItem.CartItemCustomData.SetValue("CustomDataString", "Hello");

cartItem.Update();

// Via the OrderItemInfo
ICollection<OrderItemInfo> orderItems = OrderItemInfoProvider
    .GetOrderItems(orderId);

OrderItemInfo orderItem = orderItems.First();

orderItem.OrderItemCustomData.SetValue("CustomDataNumber", 10);
orderItem.OrderItemCustomData.SetValue("CustomDataString", "Hello");

orderItem.Update();

Where is it stored in the db?

COM_OrderItem.OrderItemCustomData

What will it look like?

<CustomData>
    <CustomDataNumber>10</CustomDataNumber>
    <CustomDataString>Hello</CustomDataString>
</CustomData>

OrderItemProductDiscounts

How do we populate it?

This field is populated by any catalog discounts we have defined for our store in the CMS. These can be managed in the "Catalog Discounts" module.

For the example below, I've created a catalog discount named "Test Product 5% off" which applies a percentage discount of 5% to a single product named "Test Product".

This means the "Test Product" needs to be in my order for this discount to be applied and the field to be populated ✔.

SKUInfo sku = SKUInfoProvider
    .GetSKUs()
    .WhereEquals(nameof(SKUInfo.SKUName), "TestProduct")
    .TopN(1)
    .FirstOrDefault();

var shoppingService = Service.Resolve<IShoppingService>();

ShoppingCartInfo cart = shoppingService.GetCurrentShoppingCart();

shoppingService.AddItemToCart(sku.SKUID, 1);

Note that this is the one discount/coupon related field where the discount value and not the discounted amount is stored.

So, for example, a Value of "0.05" for a catalog discount of 5% would be stored and not "1.00" for a 10% discount on a $10.00 product.

All other discount/coupon fields store the amount to be subtracted from the order or item price.

Where is it stored in the db?

COM_OrderItem.OrderItemProductDiscounts

What will it look like?

<Summary>
    <Item>
        <Name>Test Product 5% off</Name>
        <Value>0.05</Value>
    </Item>
</Summary>

OrderItemDiscountSummary

How do we populate it?

This field is populated when the order has items that are part of a Buy->Get type discount, which are defined in the CMS "Buy X Get Y" module.

These kinds of discounts state that if a customer purchases some set of products they will get a discount of some amount either on specific items (in order to encourage buying products together) or on the cheapest items in the cart (as a promotion) 🤔.

In the example below I have a discount defined that applies a 20% discount named "Test Buy X Get Y" on the product named "Test Accessory" if the order also has a product named "Test Product".

SKUInfo skuProduct = SKUInfoProvider
    .GetSKUs()
    .WhereEquals(nameof(SKUInfo.SKUName), "TestProduct")
    .TopN(1)
    .FirstOrDefault();

SKUInfo skuAccessory = SKUInfoProvider
    .GetSKUs()
    .WhereEquals(nameof(SKUInfo.SKUName), "TestAccessory")
    .TopN(1)
    .FirstOrDefault();

var shoppingService = Service.Resolve<IShoppingService>();

ShoppingCartInfo cart = shoppingService.GetCurrentShoppingCart();

shoppingService.AddItemToCart(skuProduct.SKUID, 1);
shoppingService.AddItemToCart(skuAccessory.SKUID, 1);

We can also populate this field with coupons created in the "Product Coupons" CMS module.

If we add a coupon to the shopping cart that applies to a product in the cart, the Product Coupon display name and the discount amount will be stored in the XML.

Where is it stored in the db?

COM_OrderItem.OrderItemDiscountSummary

What will it look like?

<Summary>
    <Item>
        <Name>Test Buy X Get Y</Name>
        <Value>0.20</Value>
    </Item>
</Summary>

Summary

Kentico has all sorts of nooks and crannies, hiding implementation details. Some times the defaults fulfill the needs of our business logic, but other times we need to explore these thins to understand how we can best apply customizations 🤓.

We've looked at how the XML fields of ShoppingCartInfo, ShoppingCartItemInfo, OrderInfo, and OrderItemInfo are populated, used, and stored in the database.

These fields can usually be ignored until we explicitly need them, and in those cases it's nice to have some concrete examples, like the ones above, to ensure the results we are seeing in our applications are the correct ones.

Hopefully this blog post can be a little cheat-sheet for you (and me! 😎) when working with Kentico's E-Commerce functionality.

Thanks for reading 🙏!

If you are looking for additional Kentico content, checkout the Kentico tag here on DEV:

#kentico Follow

Or my Kentico blog series:

Kentico CMS Quick Tip: Faking A Live Site For Integration Testing

Sean G. Wright — Mon, 11 Nov 2019 13:50:10 +0000

Photo by Mihály Köles on Unsplash

Overview

Integration tests give confidence in complex code interactions
Some of Kentico's APIs are difficult to test, because they depend on a live ASP.NET application context
We can fake this context if we know which parts are accessed during our test
Testing Kentico's ShoppingService lets us explore how the E-Commerce functionality works and verify the results of our custom code

Kentico Integration Tests

Integration tests in Kentico projects are perfect for simulating interactions between classes that depend on external resources, namely the database.

Many interactions with Kentico's APIs can be performed in unit tests, but some (like UserInfoProvider.IsUserInRole) require a real database connection 🤔.

Other times, our code performs a complex series of steps, working with Kentico's types in specific ways defined by our business requirements.

Unit tests might not be enough to guarantee that these interactions will operate how we expect at runtime, and integration tests might be more appropriate.

You can read an example of what we might want in an integration test in my post Kentico CMS Quick Tip: Integration Testing Roles

Kentico CMS Quick Tip: Integration Testing Roles

Sean G. Wright for WiredViews ・ Jul 29 '19 ・ 4 min read

#kentico #dotnet #testing #csharp

However, there are some APIs that don't even work 😯 in an integration test scenario because they depend on a live running ASP.NET application, interacting with things like HttpContext and Session.

Fortunately there's a solution to this predicament 😅!

Let's look at an example.

Testing `ShoppingService`

Kentico provides many service types behind interfaces that are registered with its own Service Locator, Service, found in the CMS.Core namespace.

If we are using Dependency Injection, we could always mock these interfaces in our unit tests, but that doesn't fulfill the requirement of getting validation that the runtime interactions of multiple classes (and the database) will work as we expect.

Below we will look at running an integration test that works with ShoppingService 💰.

Creating The Test Class

First, we create a standard Kentico integration test, applying the correct NUnit test attributes and creating a test method:

[TestFixture]
public class ShoppingServiceTests : IntegrationTests
{
    [Test]
    public void ShoppingService_AddItemsToCart_Will_Update_CartItems()
    {
        // ...
    }
}

You can read more about setting up integration tests in Kentico in my post Kentico 12: Design Patterns Part 8 - Setting Up Integration Tests

Kentico 12: Design Patterns Part 8 - Setting Up Integration Tests

Sean G. Wright ・ Jul 22 '19 ・ 10 min read

#dotnet #kentico #integrationtests #testing

Our Initial Attempt

In our test method, we are going to work with CMS.Ecommerce.ShoppingService (through the IShoppingService interface), calling AddItemToCart(), which we would expect to update the database, inserting a row in COM_ShoppingCartSKU (for a new shopping cart).

Below we can see how we retrieve an ShoppingService instance from the Service service locator class and then immediately call AddItemToCart().

int skuId = 118;
int quantity = 1;

var shoppingService = Service.Resolve<IShoppingService>();

shoppingService.AddItemToCart(skuId, quantity);

var cart = shoppingService.GetCurrentShoppingCart();

cart.CartItems.Count.Should().Be(1);

This test will fail because this method requires that the execution context is a live running ASP.NET application, not a test application 😢.

The AddItemToCart() method assumes there is a user associated with the current request, whether that is an anonymous user or an authenticated one.

It also assumes there is a site that the request is being processed under. That site must have a valid Kentico license to allow for the E-Commerce functionality to be accessed 😵.

In our test method there is no "current request", so trying to access it for a user (by checking the HttpContext.User.Identity), or a site (by checking HttpContext.Request.Url.Host) will fail.

The above code will throw an exception at the line shoppingService.AddItemToCart(skuId, quantity); due to a foreign key constraint caused by the shopping cart not being persisted to the database correctly 🤦🏿‍♀️.

Faking a Live Site

So, how can we "fake" a live ASP.NET application? By faking the parts that get used by the ShoppingService.

First, we assign a valid instance of HttpContext to HttpContext.Current, only filling in the values needed by the ShoppingService.AddItemToCart():

string siteUri = "https://localhost:44397";
string page = "/";

HttpContext.Current = new HttpContext(
    new HttpRequest(page, siteUri , ""), 
    new HttpResponse(null))
    {
        User = new ClaimsPrincipal(new ClaimsIdentity())
    };

The siteUri that is listed above has to be a domain that has a valid license in the CMS (in this case, localhost) 👍.

We also fill in the HttpContext.User, not with anything valid, but just ensuring nothing is null (this is due to the ShoppingService requiring this value to not be null internally).

Next, we use Kentico's VirtualContext static class to assign some values that would normally be populated by the current HTTP request.

Most of the *Context static classes source some data from VirtualContext, so setting values here will ensure they flow to the rest of Kentico's classes 🤯:

string siteCodeName = "Sandbox";
string currentUserName = "sean@wiredviews.com";

VirtualContext.SetItem(VirtualContext.PARAM_SITENAME, siteCodeName);
VirtualContext.SetItem(VirtualContext.PARAM_USERNAME, currentUserName);

I assign a real username under the VirtualContext.PARAM_USERNAME key, so that when data is pulled from the database for the "current user", real information comes back. This user is also a valid Customer within the system.

I set the site name to match the site with a domain alias matching the siteUri I used above 🧐.

Now, we can write some code to validate our faked data is being passed around Kentico's libraries and giving us the state we desire.

Specifically, there should be an authenticated user in the system, and that user should be the same one I set with the VirtualContext above 🙂:

bool isAuthenticated = AuthenticationHelper.IsAuthenticated();

isAuthenticated.Should().BeTrue();

var currentUser = MembershipContext.AuthenticatedUser;

currentUser.UserName.Should().Be(currentUserName);

Now that we have our simulated live ASP.NET context within our test method we can start making calls to ShoppingService.AddItemToCart():

int skuId1 = 118;
int skuId2 = 200;
int quantity = 1;

var shoppingService = Service.Resolve<IShoppingService>();

shoppingService.AddItemToCart(skuId1, quantity);

var cart = shoppingService.GetCurrentShoppingCart();

cart.CartItems.Count.Should().Be(1);

shoppingService.AddItemToCart(skuId2, quantity);

cart = shoppingService.GetCurrentShoppingCart();

cart.CartItems.Count.Should().Be(2);

Above, we add an item to the cart, ensure the CartItems count is 1, and then add a different item, asserting the CartItems count is 2.

If we were to debug this code, we'd see that the value returned by shoppingService.GetCurrentShoppingCart() would be a cart assigned to the site and Customer / User matching the username we populated in the VirtualContext 🤯.

This also means that if we skip deleting the cart when the test ends, and run it again, there will already be items in the cart from the previous test run - all of this data is coming from the database 🤓.

Pretty cool ⚡⚡👏!

Pros and Cons

Faking a live environment can definitely be helpful, but its not easy. We have to know what dependencies the Kentico classes have - like VirtualContext and HttpContext - to ensure we fake the correct data.

Using a decompiler, or viewing the Kentico source code (if you have access to it), is really the only option here 🤷🏽‍♀️.

That said, it allows us to automate the interaction of many complex parts of our application - potentially scripting out an entire E-Commerce process from "Add To Cart", to "Payment", and finally to "Create Order" 😮.

If you've tried to test these processes before by stepping through the checkout process on the live site, manually clicking things until something succeeds or fails, an integration test like the one above might be a nice alternative 🤗.

It also can be helpful to see exactly how different combinations of Kentico's libraries interact together and what all the different APIs really do.

An integration test is like a mini-application where we can explore ideas, but without having to pay the cost of waiting for a site to start-up with every change we make 😊.

Wrap Up

In this post we started out explaining the benefits of integration tests compared to unit tests, but realized that even integration tests can have issues when the code being tested needs to be run in an environment different than what the test simulates.

Some Kentico APIs expect a live ASP.NET request context to function correctly, which means if we want to test these we need to simulate them in our test.

Using HttpContext.Current and VirtualContext, we can simulate what Kentico's ShoppingService does when a real customer adds an item to their shopping cart 💪.

Figuring out these hidden dependencies can be difficult, but the reward is an integration test that both helps us better understand Kentico and verifies the behavior of our custom code that uses Kentico's APIs.

In the future I'd like to expand this ShoppingService integration test to include discounts, coupons, and creating an order from a shopping cart, so follow me to be alerted when I publish here on DEV 🤓.

Thanks for reading 🙏!

If you are looking for additional Kentico content, checkout the Kentico tag here on DEV:

#kentico Follow

Or my Kentico blog series:

Kentico CMS Quick Tip: Minimal JSON Web APIs with IHttpHandler and .ashx Files

Sean G. Wright — Mon, 28 Oct 2019 14:00:21 +0000

Photo by Benjamin Nwaneampeh on Unsplash

This post was inspired by a discussion I had recently with Chris Bass, an inspiring member of the Kentico developer community. Check out his blog for more Kentico content.

Kentico Portal Engine CMS + API

When we need to make calls to our Kentico CMS Portal Engine web application from the browser over XHR or from another web service, we need an API to communicate with.

There are several ways to accomplish this, each with pros and cons, depending on our requirements 🤔.

Here's another great blog post about this topic from Kristian Bortnik.

Web API 2 - The Sports Car 🏎

Kentico's documentation explains the steps for integrating Web API 2 into the CMS.

The approach is great if you need a large and robust custom API surface standing in front of the CMS - and it's an approach I've used many, many times 👍.

However, the setup isn't trivial and the solution effectively runs the Web API OWIN-based application within the CMS - which leads to some sharp edges 🔪.

Kentico REST API - Public Transportation 🚍

Kentico has a REST API built-in, which can be used to query, and modify all kinds of data within the application 🧐.

It does provide security through a Basic Authentication HTTP header and but authenticates against the normal User accounts created within Kentico.

The REST API exposes the Kentico Page data and *Info objects directly, effectively creating a projection of the database over HTTP.

Given the above, the caveat of this built-in solution is that it's verbose, not customizable, and a leaky abstraction 😞.

IHttpHandler - The Commuter Car 🚗

For those simple scenarios where we only need a handful of endpoints, exposing a limited set of data, curated and filtered for us, we would like a way to build an API... without all the API.

A nice solution to this problem is the ASP.NET IHttpHandler, which can be exposed through an .ashx file in our CMS project.

You can read more about how IHttpHandler works in Microsoft's documentation.

IHttpHandler gives us extremely low-level to an incoming HTTP Request and the outgoing HTTP Response.

There's no WebForms code here, just the raw request and response 😮.

This is perfect for our use-case since we don't want to render HTML through a complex web of page lifecycle events and user controls 👏.

Let's take a look at some code for a concrete example of how all of this works.

I see the IHttpHandler solution as ideal for small client-side integrations and also JSON-based server-to-server integrations with existing, in-production, Kentico CMS sites that can't risk big architectural changes.

I've done both, but we'll look at the client-side solution today.

Example: An E-Commerce Store with Dynamic Prices

Imagine we have a Business-to-Business (B2B) e-commerce application where the prices and inventory need to be pulled live from a back-end warehousing or ERP system (not Kentico).

We don't want to delay the loading of a product details page each time a visitor requests it because we need to fetch the pricing - that would hurt SEO and the User Experience ☹!

Instead, we want to cache the product details page and then, via JavaScript, request the price independently 😁.

So, we need a simple API endpoint that can forward this request on to the back-end system.

Creating the .ashx File

Let's open our Kentico CMS solution, expand the project, and then the CMSPages folder.

Right-click on the CMSPages folder and select "Add" -> "Generic Handler".

We're going to name this handler ProductApi and Visual Studio will add the .ashx extension for us.

IIS already knows how to process requests for .ashx files, so even if you haven't worked with this file type before, there's no extra work necessary to use it in your application 🤓.

What we end up with is a class named ProductApi that looks like the following:

public class ProductApi : IHttpHandler
{

    public void ProcessRequest(HttpContext context)
    {
        context.Response.ContentType = "text/plain";
        context.Response.Write("Hello World");
    }

    public bool IsReusable
    {
        get
        {
            return false;
        }
    }
}

Handling the Request

Now we need to handle the incoming request from the browser.

We have the raw HttpContext to work with here. This is good, because we don't want the typical Web Forms infrastructure to get in our way, but it also means a bit more work for us 😑.

The ProcessRequest method is where we will do all of our work with the HTTP Request.

Let's assume that the browser is going to send an XHR request, with a skuid specified as a query string parameter, and it will expect a JSON response in return.

Here's ProcessRequest with some validation and error handling:

public void ProcessRequest(HttpContext context)
{
    // Set this first
    context.Response.ContentType = "application/json";

    string method = context.Request.HttpMethod;

    if (!string.Equals(method, "GET", StringComparison.OrdinalIgnoreCase))
    {
        context.Response.StatusCode = 400;

        return;
    }

    string skuIdParam = context.Request.QueryString.Get("skuid");

    int skuId = ValidationHelper.GetInteger(skuIdParam, 0);

    if (skuId == 0)
    {
        context.Response.StatusCode = 400;

        return;
    }

    SKUInfo sku = SKUInfoProvider.GetSKUInfo(skuId);

    if (sku is null)
    {
        context.Response.StatusCode = 404;

        return;
    }

    // continue processing ...

Creating the Response

Now that we have handled all the potential issues, we can get our back-end system identifier out of the sku object and request the most up-to-date values.

For our example we will pretend the response comes back in the following shape:

public class ProductStats
{
    public decimal Price { get; set; }
    public int Inventory { get; set; }
}

Let's get hand-wavy 👋 here and assume we were successful in getting values back from our back-end system and we now want to send them back to the browser.

These last few steps are pretty simple:

Get the ProductStats response from the back-end system
Use Newtonsoft.Json to serialize the C# object into a JSON string
Write the JSON string as the HTTP response

    // continue processing ...

    ProductStats response = // response from our back-end system

    string responseText = JsonConvert.SerializeObject(
        response, 
        serializationSettings);

    context.Response.Write(responseText);
}

You might have noticed the serializationSettings parameter above. That can be customized to your preferences and use-case, but it allows you to define how Newtonsoft.Json produces JSON from your C#.

I typically store this in a static readonly field in my IHttpHandler, and these are the settings I tend to use 😎:

private static readonly JsonSerializerSettings serializationSettings = 
    new JsonSerializerSettings
    {
        Formatting = Formatting.None,
        ContractResolver = new CamelCasePropertyNamesContractResolver(),

        // UTC Date serialization configuration
        DateFormatHandling = DateFormatHandling.IsoDateFormat,
        DateParseHandling = DateParseHandling.DateTimeOffset,
        DateTimeZoneHandling = DateTimeZoneHandling.Utc,
        DateFormatString = "yyyy-MM-ddTHH:mm:ss.fffK",
    };

Using Our API

So what does using this "API" look like?

Well, we can request the "API" in the browser like so:

But what about from JavaScript? Well, that's just as easy 😀!

I'm going to assume we're supporting modern browsers, so legacy fallbacks are up to the reader 😏:

(async () => {
    const params = new URLSearchParams({ skuid: 10 });

    const response = await fetch(`/CMSPages/ProductApi.ashx?${params}`);

    const { price, inventory } = await response.json();

    console.log('Price', price);
    console.log('Inventory', inventory);
})()

Who would have thought we could create a completely custom JSON based integration API in just a couple of minutes 🤗!?

Bonus: All the Context

I would also like to note that since the HTTP request is going to the same domain that the JavaScript loaded under, there's no annoying cookie or CORS restrictions 🧐.

All cookies for the current domain are sent back to the server with every HTTP request, even XHR requests to our .ashx file.

This means that the normal Kentico *Context classes that give us access to the ambient request data, like the current authenticated user (MembershipContext) and the current shopping cart (ShoppingCartContext) are all still available in our ProductApi class ⚡.

If we want to respond with additional discounts for Customers in different groups, or send the current user's ID with the SKU Id to our back-end system to get product recommendations, we can do that too 😄!

How about displaying a shipping time estimate based on information gathered from the Browser Geolocation API and the items in the shopping cart? Yup, we could do that 😃.

Wrap Up

While Kentico's Web API 2 integration approach and the built-in REST API provide a lot of functionality, they don't quite fit the requirements for a small, custom, minimalist endpoint exposed by the CMS for XHR requests from the browser.

Fortunately, IHttpHandlers and .ashx files give us a quick and dirty way to stand up an endpoint using low-level ASP.NET features, without losing out on the functionality of the CMS 👍.

If you try this approach out, let me know what you think!

Thanks for reading 🙏!

If you are looking for additional Kentico content, checkout the Kentico tag here on DEV:

#kentico Follow

Or my Kentico blog series:

Kentico Connection: Denver 2019 - My Experiences

Sean G. Wright — Thu, 10 Oct 2019 13:25:22 +0000

All photos by Me :)

I previously wrote about my expectations for Kentico Connection: Denver 2019 conference:

Kentico Connection: Denver 2019 - My Expectations

Sean G. Wright for WiredViews ・ Sep 30 '19

#kentico #mvc #conference #cms

Having now attending the conference and spent nearly a week out in Denver, Colorado, I'd like to reflect on the event and whether or not my expectations were met 🤔.

What I Experienced

First-Time Attendee

I definitely felt like a first-time attendee, which had its pros and cons.

Everything about the conference was new to me - the structure, content, personality, and especially the people 😮.

Having not been engaged with the Kentico community previously, this was the first time I ever spoke to nearly all the people there, and it was definitely the first time I met any face-to-face.

While other attendees were catching up like old friends, I was being bombarded (in the best way possible!) by handshakes, new names and faces, and questions about my blog and presentation.

I can't really compare the only other conference I know, NG-Conf, to Kentico Connection, because Angular has such a larger reach and community, whereas Kentico is a much more niche product.

That said, the things I've always enjoyed about NG-Conf held true for Kentico Connection 😀:

Friendly people
Great conversations
Welcoming community
Well organized conference
Solid presenters and talks
Exciting product announcements
Leaving with a desire to return next year!

The Community

I now feel, more than ever, connected and engaged with the larger Kentico community - and it's very reassuring to know that there is a Kentico community out there, excited for new developers and new voices 🤗.

I received lots of great feedback about my Kentico-related blog posts here on DEV, and my presentation.

It's really nice to know that everything I've been writing about Kentico is helping others and, in some cases, inspiring others to start blogging and participating in the community 😎.

So, I now want to report my findings clearly: The Kentico community is out there and wants you to join it. If your company is looking for a CMS solution and you are unsure about which product will provide the development support you feel you need, check out Kentico.

The City

I stayed in an AirBnb in Denver, which was the right decision because it gave me a nice 15 minute walk 🚶‍♂️, to and from the hotel where the conference was, each day.

I stayed in one of my favorite parts of Denver, just a bit south of Five Points, near a bunch of great craft breweries and restaurants.

The highlights for me were:

Zocalito Latin Bistro - great mole and Oaxacan cuisine 🍠

Woods Boss Brewing Company - cool space, solid craft beer 🍻

Goed Zuur - eclectic beer (lots of sours) and charcuterie... mmm 🍺🥓🧀

The Company

I had been looking forward to conversations and general brain-picking with the Kentico employees, and I didn't leave the conference disappointed.

I met product owners, most of the developer relations (devrel) team, and the Kentico EMS technical lead.

The devrel team did a great job of reaching out to me at the conference and making sure I knew they appreciated the content I've been putting out for the Kentico community here.

And honestly, I think this - simple 'thank you's - is something that is easy to forget about 😊.

Those of of us who blog and contribute to open source know how much time goes into these efforts and we don't expect or demand recognition, but when we get some, it instantly recharges our inspiration and motivation ⚡.

Thanks guys 🙏!

It was also really cool to talk with the Kentico Kontent and Kentico EMS product owners/representatives about their thoughts on the things they are in charge of.

I feel I now have a much better idea of where Kentico, as an organization, sees its products, and also where and how it wants to grow them.

I've tried to explain what I learned and my impressions to my co-workers at WiredViews so that we can position ourselves best to support businesses using Kentico EMS and Kentico Kontent.

Finally, I had a fantastic conversation, at one of the post-conference events, with the technical lead for Kentico EMS.

I was able to talk 'shop' and ask all the questions I had, from a technical perspective, about Kentico as a solution, its implementation details, the plans for bringing Kentico to .NET Core, and how some of its APIs and features might change in the near and longer-term future 🤓.

These kind of conversations are why I value going to conferences, and why I'd recommend you attend a Kentico Connection event if you work with Kentico as a developer.

What I Learned

ASP.NET Core

ASP.NET Core is coming to Kentico EMS, and it's coming faster than you might think ⌚.

Kentico 2020 / Kentico 13 / Kentico Phoenix are all monikers of the same thing - the next generation of Kentico EMS being built on ASP.NET Core so that developers can leverage the latest and greatest in the .NET ecosystem.

Planned for (if I remember correctly) September, 2020, the next version of Kentico is going to be a great thing for us devs 👍.

That said, the move from .NET Framework and MVC 5 to .NET Core and ASP.NET Core might require some work for developers and businesses.

All the internal (and 3rd party) .NET libraries, that have been leveraged repeatedly to speed up development time, need to be .NET Core compatible if they are going to be used in the next version of Kentico.

Kentico has been preparing for their migration over the past several versions, but we need to prep our code as well.

If you are looking to start migrating to .NET Core early, check out my post Kentico 12 Class Libraries with Modern .NET Core Features 🧐:

Kentico 12 Class Libraries with Modern .NET Core Features

Sean G. Wright ・ Jun 1 '19

#csharp #dotnet #dotnetcore #kentico

I'm, to put it simply, super-hyped for the opportunity to build Kentico EMS applications with ASP.NET Core, and I'm counting down the days 😃!

The MVC 5 Transition

In the US, Kentico MVC adoption is sitting at 40% (which is apparently lower than Europe, but I don't have their stat). This means that teams are moving forward with the transition away from Web Forms and Kentico Portal Engine development and towards MVC 5 with Kentico 12.

I find this super exciting!

Yes, there's still 60% to go, but this change isn't a trivial one and for lots of teams, the Portal Engine development process has been refined to perfection over many years - the same can't be said for estimating project deadlines and complexity for Kentico + MVC 😑.

Therefore, seeing 40% adoption is, I think, encouraging for the larger Kentico community. There are going to be resources for those who haven't made the switch yet, in blog posts, open source projects, and a general confirmation that "Yes, this is possible."

I know my presentation raised lots of questions from other developers and business leaders at the conference, but the feeling I got was that these questions weren't coming from a place of apprehension, but rather a desire to be armed with the best tools when venturing into unfamiliar lands 🤠.

Developers in the Kentico community are smart and will be able to adopt MVC as a technical solution, if they haven't already. The real question remaining is, how long will it take to be as comfortable with MVC as they are with Portal Engine?

For those interested, here you can find the link to the slides for my presentation From the Ground Up: Kentico 12 MVC Design Patterns.

Even if you saw my presentation, I had to 'hide' a large number of slides to fit within the time constraints, so there's some content in there I didn't get to share in Denver 😉.

Kentico Kontent

I've only explored Kentico Kontent briefly, working with the Gridsome plugin, but I find the idea of Content as a Service (Caas) very interesting.

At Kentico Connection, Kentico Kontent was presented as a solution for enterprises wishing to have centralized content management, both for multi-channel delivery (think Web, Mobile, Smart-home devices, ect...) and organizational governance (who can edit what and ensuring content and messaging are consistent across an organization) 🤯.

The price points for Kentico Kontent definitely reflect it being targeted at more mature businesses, but the free tier does look like it might be a great option for smaller companies that might not fit with a Kentico EMS solution, but still want a fully customized and fast CMS solution.

I plan on blogging some about my explorations into Kentico Kontent, and some leaders in the Kentico community have already started to here on DEV:

MMT & GatsbyJS Meetup

Matt Nield ・ Oct 9 '19

#gatsby #kenticokontent #graphql #webdev

Adding and retrieving localized strings from Kentico Cloud to GatsbyJS and GraphQL

Ilesh Mistry ・ Aug 22 '19

#gatsby #graphql #kenticocloud #kentico

What I Brought Back

After recovering from an exciting but exhausting week in Denver, and catching up on everything I missed back at the office, I had a great meeting with my co-workers, describing to them my impressions of the Kentico Connection conference and what my key takeaways were.

I think, more than anything, what I've come back with is a desire to stay engaged with the larger Kentico community and do my small part to help it grow and mature 😁.

Based on my conversations with other developers at the conference, I feel confident that WiredViews' technical approach to Kentico 12 MVC projects is very solid, but we are definitely novices when it comes to exploring the opportunities enabled by Kentico Kontent.

Based on my conversations with business leaders, I feel confident that WiredViews is well positioned in the Kentico solutions marketplace to help businesses implement their Kentico projects with our unique skill-sets and deep pool of experience 😎.

However, there's lots of changes always happening in the CMS, marketing, and custom web development space and hearing about the struggles and successes of other businesses was very enlightening.

Wrap Up

If you've made it this far, I hope you are either a Kentico Connection attendee already or a newly converted future attendee 😆.

Kentico, as a company, is taking its products in exciting new directions.

The businesses using these products have built relationships with each other over many years and continue to believe in Kentico as a great solution for content management, due to their repeated success stories.

The developers responsible for implementing and building Kentico-based solutions have created a strong and growing community that I was warmly welcomed into.

I think all these things make it clear why I'm definitely looking forward to the next Kentico Connection in 2020 👏👏.

Time to start counting down the days!

If you are looking for additional Kentico content, checkout the Kentico tag here on DEV:

#kentico Follow

Or my Kentico blog series:

Forem: WiredViews

Bits of Xperience: Displaying Rich Text After a Form Submission

📚 What Will We Learn?

❓ What Happens After a Form is Submitted?

🗃 How to Customize the Form Management UI

📅 How to Customize Razor Class Libraries

🏁 Conclusion

References

#kentico Follow

#xperience Follow

Bits of Xperience: Reducing CLS when Rendering Images

📚 What Will We Learn?

🌊 Cumulative Layout Shift (CLS)

Reducing CLS with Images and width and height HTML Attributes

Getting an Image's Dimensions in Xperience

Image Dimensions and Media Files

Always Retrieve the Full Image!

🏁 Conclusion

References

#kentico Follow

#xperience Follow

Bits of Xperience: Supercharged Page Custom Data Fields

📚 What Will We Learn?

❓ What are Page "Custom Data" fields?

🗃 What do the Page "Custom Data" Page Fields Lack?

📅 Using Global Events and Page "Custom Data"

🎛 Custom Form Controls and Control Extenders

🏗 Control Extender

👵🏽 Inheriting a Form Control

📃 Using a Page "Custom Data" Form Control

🏁 Conclusion

References

#kentico Follow

#xperience Follow

Bits of Xperience: The Hidden Cost of IPageUrlRetriever.Retrieve

📚 What Will We Learn?

🎣 What is the IPageUrlRetriever?

🧙🏽‍♀️ Which Method Do We Choose?

⚔ Retrieve(string) vs Retrieve(TreeNode)

🔥 More Pitfalls 💣

🏆 Optimal URL Generation

Conclusion

References

#kentico Follow

#xperience Follow

Bits of Xperience: Localizing XHR Requests in Kentico Xperience 13.0

📚 What Will We Learn?

🌍 What is Localization?

🔍 How does Xperience Figure Out a Request's Culture?

🧭 Finding the Request Culture in API Endpoints

🤝🏻🤝🤝🏾 Passing the Culture

🧠 Conclusion

References

#kentico Follow

#xperience Follow

Kentico CMS Quick Tip: Using Font Awesome Icons for Custom Page Types

Our Requirements

How Can We Assign Icons to Custom Page Types?

Existing Solution

Our Solution - Use Font Awesome 5

Extract the Font Awesome Assets

Copy the Webfonts folder to Xperience

Convert the Metadata to a Manifest

Adapt the CSS File

Update our Project

Conclusion

#xperience Follow

#kentico Follow

Kentico CMS Quick Tip: Azure Active Directory Authentication

Our Requirements

How Does the Built In Authentication Work?

Existing Solutions

Built-In Claims Based Authentication

Portal Engine Public Site Authentication

Our Solution

Customizing the Logon Form

Creating a Custom IHttpHandler

Adding the Handler to the web.config

Creating an Application Registration in Azure

Adding Our Application Settings

Reducing CLS with Images and `width` and `height` HTML Attributes

Creating a Custom `IHttpHandler`

Adding the Handler to the `web.config`

Creating Our `WhitelistEmailProvider`

Creating `EmailWhitelistSettings`

Customizing the `WhitelistEmailProvider`

Testing `ShoppingService`