Virtual Happy Hour this month, Jun 28, we'll be getting a sneak preview at our soon to launch SaaS CMS!

Try our conversational search powered by Generative AI!

Scott Reed
Mar 9, 2023
(25 votes)

Optimizely DXP Health Checks and Creating Custom Checks


In this blog I'm going to be talking through the standard Azure health checking system and how the DXP is setup to operate health checks. Then I'm going to explain how to easily create your own health checks to allow monitoring parts of the system so that unhealthy instances can be easily removed.

Thanks as well to Valdis and Mark Hall who helped me get this point!

Azure Heath Checks

Within Azure there is a feature called a heath check which is designed to allow you to provide information about the state of your application and if it's healthy or unhealthy. This allows the load balancer to deterimine if there are any unhealthy instances and remove them so that the overall health of the application can recover quickly as shown.

Health check navigation in Azure Portal 

Optimizely DXP Health Checks

Optimizely has a specific setup of heathcheck that's set up in the middleware and configured as standard in the Azure WebApps hosted by the DXP.

The following is setup as standard within the DXP WebApps

As you can see there is a specific route that has been configured for Optimizely health checks. So how does this all work?

Within a typical DXP startup.cs you'll have a call to


And if we decomiple this code we see a specific bit of code that sets up this health check configuration

 public static IServiceCollection AddCloudPlatformHealthCheck(this IServiceCollection services)
   services.TryAddEnumerable(ServiceDescriptor.Singleton<IEndpointRoutingExtension, CloudPlatformHealthCheckEndpointRoutingExtension>());
   services.AddHealthChecks().AddCmsHealthCheck(tags: ((IEnumerable<string>) new string[2]
   })).AddCmsWarmupHealthCheck(tags: ((IEnumerable<string>) new string[1]
   return services; 

This code does a few things

  1. Sets up the routing for the /episerver/health
  2. Adds the CmsHeathCheck which loads the class CmsHealthCheck (This checks some information about the schema / database version)
  3. Adds the AddCmsWarmupHealthCheck which does checks for a warm up using pings defined in the environments WEBSITE_HEALTHCHECK_MAXPINGFAILURES

So this does a few things to allow Optimizely to report if the Instance is healthy or unhealthy but what about if we want to add to this?

Adding Custom Checks

This is actually really easy based upon what we've seen here

  1. Create a class that inherits IHealthCheck
  2. Create an extension method to register is part of the IHealthChecksBuilder
  3. Add it to the startup.cs using the AddHealthChecks() extension

Create a class that inherits IHealthCheck

My class will specifically force an unhealthy state so we can test it in postman but in your own code obviously do a check for whatever you want and return Healthy if it's all okay!

public class CustomHealthCheck : IHealthCheck
    public Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, CancellationToken cancellationToken = new CancellationToken())
        return Task.FromResult<HealthCheckResult>(HealthCheckResult.Unhealthy("Test failed"));

Create an extension method to register is part of the IHealthChecksBuilder

public static class CustomHeathCheckExtensions
    public static IHealthChecksBuilder AddCustomHealthCheck(
        this IHealthChecksBuilder builder,
        string name = "custom-health-check",
        HealthStatus status = HealthStatus.Unhealthy,
        IEnumerable<string> tags = null)
        return builder.AddCheck<CustomHealthCheck>(name, new HealthStatus?(status), tags);

Add it to the startup.cs using the AddHealthChecks() extension

Add it on the end of the services expressions as shown here for Alloy



A quick note on this is that adding .AddCmsCloudPlatformSupport(_configuration) locally will cause an error so a way to test this locally is to comment this out and manually register the .AddCloudPlatformHealthCheck() as shown below


Then with this is place you'll get an unhealthy response back, as shown in postman when hitting that endpoint


Hopefully this helps explain exactly how the heath checking system is working in a bit more detail and gives you some ideas should you want to be able to have greater control is telling the load balancer when your instance is unhealthy :-)

Mar 09, 2023


Van Pham Hong
Van Pham Hong Mar 10, 2023 01:20 AM

Thanks Scott.

James Wilkinson
James Wilkinson Mar 10, 2023 12:32 PM

Great article thanks Scott 

Please login to comment.
Latest blogs
Remove a segment from the URL in CMS 12

Problem : I have created thousands of pages dynamically using schedule jobs with different templates (e.g. one column, two columns, etc..) and stor...

Sanjay Kumar | Jun 21, 2024

Copying property values part 2

After publishing my last article about copying property values to other language versions, I received constructive feedback on how could I change t...

Grzegorz Wiecheć | Jun 18, 2024 | Syndicated blog

Enhancing online shopping through Optimizely's personalized product recommendations

In this blog, I have summarized my experience of using and learning product recommendation feature of Optimizely Personalization Artificial...

Hetaxi | Jun 18, 2024

New Series: Building a .NET Core headless site on Optimizely Graph and SaaS CMS

Welcome to this new multi-post series where you can follow along as I indulge in yet another crazy experiment: Can we make our beloved Alloy site r...

Allan Thraen | Jun 14, 2024 | Syndicated blog