Kentico CDN integration

Introduction

A Kentico CDN integration can move application stylesheets, JavaScript, icons, and other public static files closer to visitors while Xperience pages, administration, and dynamic requests continue to run on the origin server.

This guide shows how to define one CDN base URL, expose it through a small Razor helper, and use that helper for static asset references in an ASP.NET Core project. The procedure was tested with Xperience by Kentico 31.7.3.

Before you start

  • This tutorial shows how to integrate a CDN service into a website. In this particular demo example we will use:
    • barsoom-cdn.cdnsun.org as the CDN Service Domain, and
    • https://barsoom.cdnsun.org as the website URL (i.e. barsoom.cdnsun.org is the Origin Domain).
  • Please visit the Services/How-To section to obtain your CDN Service Domain.
  • Before you take any steps please back up your files and database.
  • To integrate a CDN service on https:// website the CDN service must have SSL enabled.
  • If your website embeds custom fonts then please first enable CORS for them.
  • Before you take any steps please make sure that your CDN Service Domain is ready-to-use here.

Create CDN Static service

Please refer to Creating a CDN Static service for more details.

Configure static asset URLs in Xperience by Kentico

  1. The code samples use Dancing Goat, Kentico's sample website project. DancingGoat is the root namespace used by the sample application. Replace it wherever shown with your application's root namespace.

    Add a Cdn section to the application's appsettings.json file. Set BaseUrl to the complete HTTPS URL of the CDN Service Domain:

    {
  "Cdn": {
    "BaseUrl": "https://barsoom-cdn.cdnsun.org"
  }
}

    Environment-specific configuration can override this value without changing the Razor views.

  2. Create Helpers/CdnAssetUrl.cs. The helper removes duplicate slashes, prefixes public asset paths with the configured URL, and retains origin-relative paths if the setting is empty:

    using Microsoft.Extensions.Configuration;

namespace DancingGoat.Helpers;

public sealed class CdnAssetUrl
{
    private readonly string cdnBaseUrl;

    public CdnAssetUrl(IConfiguration configuration)
    {
        cdnBaseUrl = configuration["Cdn:BaseUrl"]?.TrimEnd('/') ?? string.Empty;
    }

    public string Url(string relativePath)
    {
        string assetPath = relativePath.TrimStart('/');

        return string.IsNullOrEmpty(cdnBaseUrl)
            ? $"/{assetPath}"
            : $"{cdnBaseUrl}/{assetPath}";
    }
}

  3. Register the helper with the dependency injection container in Program.cs after the project's other application services:

    using DancingGoat.Helpers;

builder.Services.AddDancingGoatServices();
builder.Services.AddSingleton<CdnAssetUrl>();

  4. Inject the helper into Razor views through Views/_ViewImports.cshtml:

    @inject DancingGoat.Helpers.CdnAssetUrl CdnAssets

    If the project keeps page templates under a separate PageTemplates directory, add the same line to PageTemplates/_ViewImports.cshtml.

  5. Open the shared layout used by the public site and replace origin-relative references to static files with calls to the helper. For example:

    <link rel="icon"
      href="@CdnAssets.Url("Content/Images/favicon.svg")"
      type="image/svg+xml" />
<link rel="stylesheet"
      href="@CdnAssets.Url("Content/Styles/Site.css")" />

<img src="@CdnAssets.Url("Content/Images/logo.svg")"
     alt="Site logo" />

<script src="@CdnAssets.Url("Scripts/mobileMenu.js")"></script>

    Keep page links, forms, administration URLs, and other dynamic application routes on the origin domain.

  6. Update any remaining literal public references under /Content and /Scripts in views and page templates. If a stylesheet loads custom fonts, follow the CORS requirements in Using custom fonts with CDN - setting CORS.

  7. Optional Content Hub assets: the helper above targets application static files. Published Content Hub assets use Xperience-generated /getContentAsset/... paths. To deliver public assets through the CDN as well, preserve the generated path and prefix it with the CDN Service Domain:

    https://barsoom-cdn.cdnsun.org/getContentAsset/<generated-path>

    Apply this only to public, published assets. See the Xperience by Kentico Content item assets documentation for asset publication and URL behavior.

  8. Open the public site and confirm that the frontend remains styled normally and static assets load from the CDN Service Domain.

    Styled Xperience by Kentico frontend loading static assets through the CDN Service Domain

Verify & Troubleshoot

  • View HTML source code of your web pages to verify that you are using CDN, you should see source attribute of your images, CSS, JavaScript, etc. beginning with your CDN Service Domain.
    Frontend HTML proof that static assets are loaded from the CDN Service Domain
  • Don't see your CDN Service Domain in the source code of your web pages? If your website is using any cache plug-in/mechanism then you might want to clear/flush its cache.
  • Having trouble with custom fonts? Please refer to Using custom fonts with CDN - setting CORS for more details.
  • Still having trouble? Check your CDN URLs using our content check tool or please refer to Debugging a CDN service for more hints.

Contact Us

  _____      ___     ______   
 / ____||   / _ \\  |      \\ 
/ //---`'  | / \ || |  --  // 
\ \\___    | \_/ || |  --  \\ 
 \_____||   \___//  |______// 
  `----`    `---`   `------`