Background Jobs: Rewrite RecurringHostedServiceBase with SemaphoreSlim and add signalling support

src/Umbraco.Infrastructure/BackgroundJobs/DelayCalculator.cs

@@ -60,8 +60,8 @@ internal static TimeSpan GetDelay(
             }
 
             // Otherwise start at scheduled time according to cron expression, unless within the default delay period.
-            DateTime firstRunOccurance = cronTabParser.GetNextOccurrence(firstRunTime, now);
-            TimeSpan delay = firstRunOccurance - now;
+            DateTime firstRunOccurrence = cronTabParser.GetNextOccurrence(firstRunTime, now);
+            TimeSpan delay = firstRunOccurrence - now;
             return delay < defaultDelay
                 ? defaultDelay
                 : delay;

src/Umbraco.Infrastructure/BackgroundJobs/IRecurringBackgroundJob.cs

@@ -1,38 +1,71 @@
-using Umbraco.Cms.Core;
 using Umbraco.Cms.Core.Sync;
 
 namespace Umbraco.Cms.Infrastructure.BackgroundJobs;
 
 /// <summary>
-///     A recurring background job
+/// A recurring background job.
 /// </summary>
 public interface IRecurringBackgroundJob
 {
-    static readonly TimeSpan DefaultDelay = System.TimeSpan.FromMinutes(3);
-    static readonly ServerRole[] DefaultServerRoles = new[] { ServerRole.Single, ServerRole.SchedulingPublisher };
+    /// <summary>
+    /// The default delay to use for recurring tasks for the first run after application start-up if no alternative is configured.
+    /// </summary>
+    [Obsolete("Use RecurringBackgroundJobBase.DefaultDelay instead. Scheduled for removal in Umbraco 19.")]
+    static readonly TimeSpan DefaultDelay = RecurringBackgroundJobBase.DefaultDelay;
+
+    /// <summary>
+    /// The default server roles that recurring background jobs run on.
+    /// </summary>
+    [Obsolete("Use RecurringBackgroundJobBase.DefaultServerRoles instead. Scheduled for removal in Umbraco 19.")]
+    static readonly ServerRole[] DefaultServerRoles = RecurringBackgroundJobBase.DefaultServerRoles;
 
     /// <summary>
     /// Timespan representing how often the task should recur.
     /// </summary>
+    /// <value>
+    /// The period.
+    /// </value>
     TimeSpan Period { get; }
 
     /// <summary>
-    /// Timespan representing the initial delay after application start-up before the first run of the task
-    /// occurs.
+    /// Timespan representing the initial delay after application start-up before the first run of the task occurs.
     /// </summary>
-    TimeSpan Delay { get => DefaultDelay; }
+    /// <value>
+    /// The delay.
+    /// </value>
+    TimeSpan Delay => RecurringBackgroundJobBase.DefaultDelay; // TODO (V19): Remove the default implementation
 
     /// <summary>
-    /// Gets the server roles for which this recurring background job is intended.
+    /// Gets the server roles the task executes on.
     /// </summary>
-    ServerRole[] ServerRoles { get => DefaultServerRoles; }
+    /// <value>
+    /// The server roles.
+    /// </value>
+    ServerRole[] ServerRoles => RecurringBackgroundJobBase.DefaultServerRoles; // TODO (V19): Remove the default implementation
 
+    /// <summary>
+    /// This event should be raised when the <see cref="Period" /> property changes to notify the background job manager to update the schedule for this job.
+    /// </summary>
     event EventHandler PeriodChanged;
 
     /// <summary>
-    /// Executes the logic associated with the recurring background job asynchronously.
+    /// Runs the background job.
     /// </summary>
-    /// <returns>A <see cref="System.Threading.Tasks.Task"/> that represents the asynchronous execution of the background job.</returns>
+    /// <returns>
+    /// A task representing the asynchronous operation.
+    /// </returns>
+    [Obsolete("Use RunJobAsync(CancellationToken) instead. This method will be removed in Umbraco 19.")]
     Task RunJobAsync();
-}
 
+    /// <summary>
+    /// Runs the background job with cancellation support.
+    /// </summary>
+    /// <param name="cancellationToken">A cancellation token that is signaled when the host is shutting down.</param>
+    /// <returns>
+    /// A task representing the asynchronous operation.
+    /// </returns>
+    Task RunJobAsync(CancellationToken cancellationToken)
+#pragma warning disable CS0618 // Type or member is obsolete
+        => RunJobAsync(); // TODO (V19): Remove the default implementation when RunJobAsync() is removed
+#pragma warning restore CS0618 // Type or member is obsolete
+}

src/Umbraco.Infrastructure/BackgroundJobs/RecurringBackgroundJobBase.cs

@@ -0,0 +1,34 @@
+using Umbraco.Cms.Core.Sync;
+
+namespace Umbraco.Cms.Infrastructure.BackgroundJobs;
+
+/// <summary>
+/// Base class for recurring background jobs that provides default values for common properties.
+/// </summary>
+/// <remarks>
+/// Implementors only need to provide <see cref="Period" /> and <see cref="RunJobAsync(CancellationToken)" />.
+/// </remarks>
+public abstract class RecurringBackgroundJobBase : IRecurringBackgroundJob
+{
+    protected internal static readonly TimeSpan DefaultDelay = TimeSpan.FromMinutes(3);
+    protected internal static readonly ServerRole[] DefaultServerRoles = [ServerRole.Single, ServerRole.SchedulingPublisher];
+
+    /// <inheritdoc />
+    public abstract TimeSpan Period { get; }
+
+    /// <inheritdoc />
+    public virtual TimeSpan Delay => DefaultDelay;
+
+    /// <inheritdoc />
+    public virtual ServerRole[] ServerRoles => DefaultServerRoles;
+
+    /// <inheritdoc />
+    public virtual event EventHandler PeriodChanged { add { } remove { } }
+
+    /// <inheritdoc />
+    [Obsolete("Use RunJobAsync(CancellationToken) instead. This method will be removed in Umbraco 19.")]
+    public Task RunJobAsync() => RunJobAsync(CancellationToken.None);
+
+    /// <inheritdoc />
+    public abstract Task RunJobAsync(CancellationToken cancellationToken);
+}

src/Umbraco.Infrastructure/BackgroundJobs/RecurringBackgroundJobHostedService.cs

@@ -1,16 +1,15 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Logging;
-using Microsoft.Extensions.Options;
-using Serilog.Core;
 using Umbraco.Cms.Core;
-using Umbraco.Cms.Core.Configuration.Models;
+using Umbraco.Cms.Core.DependencyInjection;
 using Umbraco.Cms.Core.Events;
 using Umbraco.Cms.Core.Notifications;
 using Umbraco.Cms.Core.Runtime;
 using Umbraco.Cms.Core.Services;
 using Umbraco.Cms.Core.Sync;
 using Umbraco.Cms.Infrastructure.HostedServices;
+using Umbraco.Cms.Infrastructure.Notifications;
 
 namespace Umbraco.Cms.Infrastructure.BackgroundJobs;
 
@@ -23,45 +22,50 @@ public static class RecurringBackgroundJobHostedService
     /// Creates a factory function that produces hosted services for recurring background jobs.
     /// </summary>
     /// <param name="serviceProvider">The service provider used to create hosted service instances.</param>
-    /// <returns>A function that takes an <see cref="IRecurringBackgroundJob"/> and returns an <see cref="IHostedService"/>.</returns>
-    public static Func<IRecurringBackgroundJob, IHostedService> CreateHostedServiceFactory(IServiceProvider serviceProvider) =>
-        (IRecurringBackgroundJob job) =>
+    /// <returns>
+    /// A function that takes an <see cref="IRecurringBackgroundJob" /> and returns an <see cref="IHostedService" />.
+    /// </returns>
+    public static Func<IRecurringBackgroundJob, IHostedService> CreateHostedServiceFactory(IServiceProvider serviceProvider)
+        => (IRecurringBackgroundJob job) =>
         {
             Type hostedServiceType = typeof(RecurringBackgroundJobHostedService<>).MakeGenericType(job.GetType());
+
             return (IHostedService)ActivatorUtilities.CreateInstance(serviceProvider, hostedServiceType, job);
         };
 }
 
 /// <summary>
 /// Runs a recurring background job inside a hosted service.
-/// Generic version for DependencyInjection
 /// </summary>
-/// <typeparam name="TJob">Type of the Job</typeparam>
-public class RecurringBackgroundJobHostedService<TJob> : RecurringHostedServiceBase where TJob : IRecurringBackgroundJob
+/// <typeparam name="TJob">The type of the job.</typeparam>
+public class RecurringBackgroundJobHostedService<TJob> : RecurringHostedServiceBase
+    where TJob : IRecurringBackgroundJob
 {
-
+    private readonly IRuntimeState _runtimeState;
     private readonly ILogger<RecurringBackgroundJobHostedService<TJob>> _logger;
     private readonly IMainDom _mainDom;
-    private readonly IRuntimeState _runtimeState;
     private readonly IServerRoleAccessor _serverRoleAccessor;
     private readonly IEventAggregator _eventAggregator;
+    private readonly IEventMessagesFactory _eventMessagesFactory;
     private readonly IRecurringBackgroundJob _job;
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="RecurringBackgroundJobHostedService{TJob}"/> class, which manages the execution of a recurring background job.
+    /// Initializes a new instance of the <see cref="RecurringBackgroundJobHostedService{TJob}" /> class, which manages the execution of a recurring background job.
     /// </summary>
     /// <param name="runtimeState">Provides information about the current runtime state of the Umbraco application.</param>
     /// <param name="logger">The logger used to record diagnostic and operational information for this hosted service.</param>
     /// <param name="mainDom">The main domain instance responsible for coordinating single-instance operations across multiple application domains.</param>
     /// <param name="serverRoleAccessor">Determines the current server's role in a multi-server environment.</param>
     /// <param name="eventAggregator">Handles the publishing and subscribing of application events.</param>
+    /// <param name="eventMessagesFactory">The event messages factory.</param>
     /// <param name="job">The recurring background job instance to be managed and executed by this service.</param>
     public RecurringBackgroundJobHostedService(
         IRuntimeState runtimeState,
         ILogger<RecurringBackgroundJobHostedService<TJob>> logger,
         IMainDom mainDom,
         IServerRoleAccessor serverRoleAccessor,
         IEventAggregator eventAggregator,
+        IEventMessagesFactory eventMessagesFactory,
         TJob job)
         : base(logger, job.Period, job.Delay)
     {
@@ -70,87 +74,104 @@ public RecurringBackgroundJobHostedService(
         _mainDom = mainDom;
         _serverRoleAccessor = serverRoleAccessor;
         _eventAggregator = eventAggregator;
+        _eventMessagesFactory = eventMessagesFactory;
         _job = job;
 
         _job.PeriodChanged += (sender, e) => ChangePeriod(_job.Period);
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="RecurringBackgroundJobHostedService{TJob}" /> class, which manages the execution of a recurring background job.
+    /// </summary>
+    /// <param name="runtimeState">Provides information about the current runtime state of the Umbraco application.</param>
+    /// <param name="logger">The logger used to record diagnostic and operational information for this hosted service.</param>
+    /// <param name="mainDom">The main domain instance responsible for coordinating single-instance operations across multiple application domains.</param>
+    /// <param name="serverRoleAccessor">Determines the current server's role in a multi-server environment.</param>
+    /// <param name="eventAggregator">Handles the publishing and subscribing of application events.</param>
+    /// <param name="job">The recurring background job instance to be managed and executed by this service.</param>
+    [Obsolete("Use the overload accepting IEventMessagesFactory instead. This overload will be removed in Umbraco 19.")]
+    public RecurringBackgroundJobHostedService(
+       IRuntimeState runtimeState,
+       ILogger<RecurringBackgroundJobHostedService<TJob>> logger,
+       IMainDom mainDom,
+       IServerRoleAccessor serverRoleAccessor,
+       IEventAggregator eventAggregator,
+       TJob job)
+       : this(runtimeState, logger, mainDom, serverRoleAccessor, eventAggregator, StaticServiceProvider.Instance.GetRequiredService<IEventMessagesFactory>(), job)
+    { }
+
     /// <inheritdoc />
-    public override async Task PerformExecuteAsync(object? state)
+    public override async Task PerformExecuteAsync(CancellationToken stoppingToken)
     {
-        var executingNotification = new Notifications.RecurringBackgroundJobExecutingNotification(_job, new EventMessages());
-        await _eventAggregator.PublishAsync(executingNotification);
+        EventMessages eventMessages = _eventMessagesFactory.Get();
+        var executingNotification = new RecurringBackgroundJobExecutingNotification(_job, eventMessages);
+        await _eventAggregator.PublishAsync(executingNotification, stoppingToken);
 
         try
         {
-
             if (_runtimeState.Level != RuntimeLevel.Run)
             {
                 _logger.LogDebug("Job not running as runlevel not yet ready");
-                await _eventAggregator.PublishAsync(new Notifications.RecurringBackgroundJobIgnoredNotification(_job, new EventMessages()).WithStateFrom(executingNotification));
+                await _eventAggregator.PublishAsync(new RecurringBackgroundJobIgnoredNotification(_job, eventMessages).WithStateFrom(executingNotification), stoppingToken);
                 return;
             }
 
             // Don't run on replicas nor unknown role servers
             if (!_job.ServerRoles.Contains(_serverRoleAccessor.CurrentServerRole))
             {
                 _logger.LogDebug("Job not running on this server role");
-                await _eventAggregator.PublishAsync(new Notifications.RecurringBackgroundJobIgnoredNotification(_job, new EventMessages()).WithStateFrom(executingNotification));
+                await _eventAggregator.PublishAsync(new RecurringBackgroundJobIgnoredNotification(_job, eventMessages).WithStateFrom(executingNotification), stoppingToken);
                 return;
             }
 
             // Ensure we do not run if not main domain, but do NOT lock it
             if (!_mainDom.IsMainDom)
             {
                 _logger.LogDebug("Job not running as not MainDom");
-                await _eventAggregator.PublishAsync(new Notifications.RecurringBackgroundJobIgnoredNotification(_job, new EventMessages()).WithStateFrom(executingNotification));
+                await _eventAggregator.PublishAsync(new RecurringBackgroundJobIgnoredNotification(_job, eventMessages).WithStateFrom(executingNotification), stoppingToken);
                 return;
             }
 
-
-            await _job.RunJobAsync();
-            await _eventAggregator.PublishAsync(new Notifications.RecurringBackgroundJobExecutedNotification(_job, new EventMessages()).WithStateFrom(executingNotification));
-
-
+            await _job.RunJobAsync(stoppingToken);
+            await _eventAggregator.PublishAsync(new RecurringBackgroundJobExecutedNotification(_job, eventMessages).WithStateFrom(executingNotification), stoppingToken);
+        }
+        catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
+        {
+            _logger.LogDebug("Job canceled during shutdown.");
+            await _eventAggregator.PublishAsync(new RecurringBackgroundJobCanceledNotification(_job, eventMessages).WithStateFrom(executingNotification), CancellationToken.None);
         }
         catch (Exception ex)
         {
-            await _eventAggregator.PublishAsync(new Notifications.RecurringBackgroundJobFailedNotification(_job, new EventMessages()).WithStateFrom(executingNotification));
             _logger.LogError(ex, "Unhandled exception in recurring background job.");
+            await _eventAggregator.PublishAsync(new RecurringBackgroundJobFailedNotification(_job, eventMessages).WithStateFrom(executingNotification), stoppingToken);
         }
-
     }
 
-    /// <summary>
-    /// Asynchronously starts the recurring background job and publishes notifications before and after the job is started.
-    /// This method first publishes a <see cref="Notifications.RecurringBackgroundJobStartingNotification"/> prior to starting the job,
-    /// then calls the base implementation to start the job, and finally publishes a <see cref="Notifications.RecurringBackgroundJobStartedNotification"/>.
-    /// </summary>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
-    /// <returns>A task that represents the asynchronous start operation.</returns>
+    /// <inheritdoc />
+    [Obsolete("Override PerformExecuteAsync(CancellationToken) instead. Scheduled for removal in Umbraco 19.")]
+    public override Task PerformExecuteAsync(object? state) => PerformExecuteAsync(CancellationToken.None);
+
+    /// <inheritdoc />
     public override async Task StartAsync(CancellationToken cancellationToken)
     {
-        var startingNotification = new Notifications.RecurringBackgroundJobStartingNotification(_job, new EventMessages());
-        await _eventAggregator.PublishAsync(startingNotification);
+        EventMessages eventMessages = _eventMessagesFactory.Get();
+        var startingNotification = new RecurringBackgroundJobStartingNotification(_job, eventMessages);
+        await _eventAggregator.PublishAsync(startingNotification, cancellationToken);
 
         await base.StartAsync(cancellationToken);
 
-        await _eventAggregator.PublishAsync(new Notifications.RecurringBackgroundJobStartedNotification(_job, new EventMessages()).WithStateFrom(startingNotification));
-
+        await _eventAggregator.PublishAsync(new RecurringBackgroundJobStartedNotification(_job, eventMessages).WithStateFrom(startingNotification), cancellationToken);
     }
 
-    /// <summary>
-    /// Asynchronously stops the recurring background job service, publishing notifications before and after stopping.
-    /// </summary>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
-    /// <returns>A task that represents the asynchronous stop operation.</returns>
+    /// <inheritdoc />
     public override async Task StopAsync(CancellationToken cancellationToken)
     {
-        var stoppingNotification = new Notifications.RecurringBackgroundJobStoppingNotification(_job, new EventMessages());
-        await _eventAggregator.PublishAsync(stoppingNotification);
+        EventMessages eventMessages = _eventMessagesFactory.Get();
+        var stoppingNotification = new RecurringBackgroundJobStoppingNotification(_job, eventMessages);
+        await _eventAggregator.PublishAsync(stoppingNotification, cancellationToken);
 
         await base.StopAsync(cancellationToken);
 
-        await _eventAggregator.PublishAsync(new Notifications.RecurringBackgroundJobStoppedNotification(_job, new EventMessages()).WithStateFrom(stoppingNotification));
+        await _eventAggregator.PublishAsync(new RecurringBackgroundJobStoppedNotification(_job, eventMessages).WithStateFrom(stoppingNotification), cancellationToken);
     }
 }