Scheduler Delegation: Using Optimizely DXP Infrastructure for Queued Processing

The problem: expensive work triggered from the request path

What DXP gives you: a scheduler instance

• does not receive user-facing requests;
• is intended for backend work: scheduled jobs, background tasks and back-office operations performed by content editors;
• is part of the same deployment, so it runs your code, your configuration and your initialization modules.

Architecture overview

Design decisions and the reasoning behind them

1. Events carry intent; data stays at the source

using System.Runtime.Serialization;
using EPiServer.Events;

[DataContract]
[EventsServiceKnownType]
public class RecalculationRequest
{
    [DataMember] public string Model { get; set; } = "";
    [DataMember] public string Options { get; set; } = "";
}

2. An in-memory queue on the scheduler is enough

• If the scheduler restarts and loses its queue, the next request that sees a missing or stale result raises the event again.
• Duplicate events are harmless because the queue keeps one entry per input.

3. Batching and de-duplication give you load control

4. A de-duplicating queue keeps producers fast and memory bounded

using System.Collections.Concurrent;
using EPiServer.ServiceLocation;

[ServiceConfiguration(Lifecycle = ServiceInstanceScope.Singleton)]
public class RecalculationQueue
{
    private ConcurrentDictionary<(string Model, string Options), RecalculationRequest> _pending = new();

    public void Add(RecalculationRequest request) =>
        _pending.TryAdd((request.Model, request.Options), request);

    public IReadOnlyCollection<RecalculationRequest> Drain()
    {
        // A write racing the swap can be lost; the next miss raises it again.
        var drained = Interlocked.Exchange(ref _pending, new());
        return drained.Values.ToList();
    }

    public bool IsEmpty => _pending.IsEmpty;
}

5. One event rail, two routing modes

• Delegation on (Preproduction, Production): only the scheduler instance reacts, and it queues the item.
• Delegation off (local, simple setups): only the instance that raised the event reacts, and it processes the item immediately on a background thread.

using EPiServer.Events;
using EPiServer.Events.Clients;
using EPiServer.Framework;
using EPiServer.Framework.Initialization;
using EPiServer.Scheduler;
using EPiServer.ServiceLocation;
using Microsoft.Extensions.Options;

public abstract class DelegatingEventModule<TRequest> : IInitializableModule
    where TRequest : class
{
    protected abstract Guid EventId { get; }
    protected abstract Guid RaiserId { get; }
    protected abstract void HandleOnScheduler(TRequest request);
    protected abstract void HandleLocally(TRequest request);

    private bool DelegateToScheduler =>
        ServiceLocator.Current.GetInstance<IOptions<DelegationOptions>>().Value.Enabled;

    private static bool IsScheduler =>
        ServiceLocator.Current.GetInstance<IOptions<SchedulerOptions>>().Value.Enabled;

    public void Initialize(InitializationEngine context)
    {
        var evt = ServiceLocator.Current.GetInstance<IEventRegistry>().Get(EventId);
        evt.Raised += DelegateToScheduler ? OnSchedulerRoute : OnLocalRoute;
    }

    public void Uninitialize(InitializationEngine context)
    {
        var evt = ServiceLocator.Current.GetInstance<IEventRegistry>().Get(EventId);
        evt.Raised -= DelegateToScheduler ? OnSchedulerRoute : OnLocalRoute;
    }

    private void OnSchedulerRoute(object sender, EventNotificationEventArgs e)
    {
        if (!IsScheduler) return;                  // web instances ignore it
        if (e.Param is not TRequest request) return;
        HandleOnScheduler(request);                // typically: queue.Add(request)
    }

    private void OnLocalRoute(object sender, EventNotificationEventArgs e)
    {
        if (e.RaiserId != RaiserId) return;        // only handle what this instance raised
        if (e.Param is not TRequest request) return;
        Task.Run(() => HandleLocally(request));
    }
}

[ModuleDependency(typeof(EPiServer.Web.InitializationModule))]
public class ConfiguratorRecalculationModule : DelegatingEventModule<RecalculationRequest>
{
    internal static readonly Guid Id = new("00000000-0000-0000-0000-000000000001");
    internal static readonly Guid Raiser = Guid.NewGuid();

    protected override Guid EventId => Id;
    protected override Guid RaiserId => Raiser;

    protected override void HandleOnScheduler(RecalculationRequest request) =>
        ServiceLocator.Current.GetInstance<RecalculationQueue>().Add(request);

    protected override void HandleLocally(RecalculationRequest request) =>
        ServiceLocator.Current.GetInstance<ConfiguratorCalculator>().Recalculate(request);
}

• IsScheduler reads SchedulerOptions.Enabled, which the platform sets per instance. On DXP the scheduler is enabled only on the scheduler instance, so the check follows the real topology.
• DelegationOptions is your own options class, bound from appsettings.json. It is the configuration flag that switches between the two routing modes.
• RaiserId is generated once per process (Guid.NewGuid() in a static field). It lets an instance recognize its own events when delegation is off.
• EventId is a fixed GUID. Every instance must use the same value to subscribe to the same event.

6. The read path is defensive

using EPiServer.Events.Clients;

public class ConfiguratorResultService(
    IEventRegistry eventRegistry,
    IResultStorage storage,
    ILogger<ConfiguratorResultService> logger)
{
    private static readonly TimeSpan Ttl = TimeSpan.FromMinutes(2);

    public ConfiguratorResult GetResult(RecalculationRequest request)
    {
        var entry = storage.TryRead(request);

        if (entry is null || entry.CalculatedAt < DateTime.UtcNow - Ttl)
        {
            RequestRecalculation(request);
        }

        return entry?.Value ?? ConfiguratorResult.Fallback;
    }

    private void RequestRecalculation(RecalculationRequest request)
    {
        try
        {
            eventRegistry.Get(ConfiguratorRecalculationModule.Id)
                ?.Raise(ConfiguratorRecalculationModule.Raiser, request);
        }
        catch (Exception ex)
        {
            // A failed raise only delays the refresh; the visitor still gets an answer.
            logger.LogWarning(ex, "Recalculation request for {Model} could not be raised", request.Model);
        }
    }
}

7. The scheduled job is the batch processor

using EPiServer.PlugIn;
using EPiServer.Scheduler;

[ScheduledPlugIn(
    DisplayName = "Recalculate configurator results on demand",
    GUID = "00000000-0000-0000-0000-000000000002",
    IntervalType = ScheduledIntervalType.Minutes,
    IntervalLength = 1,
    DefaultEnabled = true,
    Restartable = true)]
public class RecalculateOnDemandJob : ScheduledJobBase
{
    private readonly RecalculationQueue _queue;
    private readonly ConfiguratorCalculator _calculator;
    private readonly ILogger<RecalculateOnDemandJob> _logger;
    private bool _stopRequested;

    public RecalculateOnDemandJob(
        RecalculationQueue queue,
        ConfiguratorCalculator calculator,
        ILogger<RecalculateOnDemandJob> logger)
    {
        _queue = queue;
        _calculator = calculator;
        _logger = logger;
        IsStoppable = true;
    }

    public override void Stop() => _stopRequested = true;

    public override string Execute()
    {
        if (_queue.IsEmpty) return "Nothing to recalculate";

        var batch = _queue.Drain();

        var done = 0;
        foreach (var request in batch)
        {
            if (_stopRequested) break;
            try
            {
                _calculator.Recalculate(request);   // calculate and write to shared storage
                done++;
            }
            catch (Exception ex)
            {
                // One failing item must not abandon the batch; the next miss re-raises it.
                _logger.LogError(ex, "Recalculation failed for {Model}", request.Model);
            }
        }

        return $"Recalculated {done} of {batch.Count} items";
    }
}

Results in production

• 1,000,000 hits (about 98%), answered from a fresh entry;
• 22,000 stale reads (about 2%), answered immediately with the previous result while the scheduler refreshes the entry;
• 0 misses. Misses only occur before the storage is first populated. After that, visitors receive the previous value of an expired entry until it is refreshed.

What enables this architecture

• Every instance runs the same deployment. Initialization modules subscribe to the event on all instances, and a single platform setting decides which one acts.
• The control path and the data path are separate. Events travel over the bus, results travel through shared storage, and the scheduler and web instances never call each other. Either path can be replaced independently.
• There is a single writer. Only the scheduler instance calculates and stores results, so every web instance reads the same value. Eventual consistency is confined to one place: the time until the next job tick.

The return path is a free choice

Trade-offs and failure modes

When to use it

• The answer contains no financial values, personal data or access decisions. Such data must be accurate and current on every request.
• Visitors ask only a fraction of all possible questions. If every answer is needed anyway, a plain scheduled job that calculates everything is simpler.

Getting started checklist

Conclusion