From 44df9390a88991b0d92a258e4a00303a45f24604 Mon Sep 17 00:00:00 2001
From: maliming <malimings@gmail.com>
Date: Mon, 11 May 2026 13:05:43 +0800
Subject: [PATCH] Improve error messages for CronExpression in
 DefaultDynamicBackgroundWorkerManager and add test for exception on
 UpdateSchedule with CronExpression

---
 .../DefaultDynamicBackgroundWorkerManager.cs  |  4 ++--
 .../IDynamicBackgroundWorkerManager.cs        |  6 +++++
 .../DynamicBackgroundWorkerManager_Tests.cs   | 24 +++++++++++++++++++
 3 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/framework/src/Volo.Abp.BackgroundWorkers/Volo/Abp/BackgroundWorkers/DefaultDynamicBackgroundWorkerManager.cs b/framework/src/Volo.Abp.BackgroundWorkers/Volo/Abp/BackgroundWorkers/DefaultDynamicBackgroundWorkerManager.cs
index 6fdbb202d0..62dce443a8 100644
--- a/framework/src/Volo.Abp.BackgroundWorkers/Volo/Abp/BackgroundWorkers/DefaultDynamicBackgroundWorkerManager.cs
+++ b/framework/src/Volo.Abp.BackgroundWorkers/Volo/Abp/BackgroundWorkers/DefaultDynamicBackgroundWorkerManager.cs
@@ -46,7 +46,7 @@ public class DefaultDynamicBackgroundWorkerManager :
         {
             throw new AbpException(
                 $"The default in-memory background worker manager does not support CronExpression for dynamic worker '{workerName}'. " +
-                "Please set Period, or use a scheduler-backed provider (Hangfire or Quartz).");
+                "Please clear CronExpression and use Period-based scheduling, or use a scheduler-backed provider (Hangfire or Quartz).");
         }
 
         await _semaphore.WaitAsync(cancellationToken);
@@ -109,7 +109,7 @@ public class DefaultDynamicBackgroundWorkerManager :
         {
             throw new AbpException(
                 $"The default in-memory background worker manager does not support CronExpression for dynamic worker '{workerName}'. " +
-                "Please set Period, or use a scheduler-backed provider (Hangfire or Quartz).");
+                "Please clear CronExpression and use Period-based scheduling, or use a scheduler-backed provider (Hangfire or Quartz).");
         }
 
         await _semaphore.WaitAsync(cancellationToken);
diff --git a/framework/src/Volo.Abp.BackgroundWorkers/Volo/Abp/BackgroundWorkers/IDynamicBackgroundWorkerManager.cs b/framework/src/Volo.Abp.BackgroundWorkers/Volo/Abp/BackgroundWorkers/IDynamicBackgroundWorkerManager.cs
index 7e625e7c9c..a897549249 100644
--- a/framework/src/Volo.Abp.BackgroundWorkers/Volo/Abp/BackgroundWorkers/IDynamicBackgroundWorkerManager.cs
+++ b/framework/src/Volo.Abp.BackgroundWorkers/Volo/Abp/BackgroundWorkers/IDynamicBackgroundWorkerManager.cs
@@ -6,6 +6,12 @@ namespace Volo.Abp.BackgroundWorkers;
 /// <summary>
 /// Manages dynamic background workers that are registered at runtime
 /// without requiring a strongly-typed worker class.
+/// <para>
+/// Implementations may differ in capabilities. Check <see cref="ISupportsRuntimeRegistration"/>
+/// before calling <see cref="AddAsync"/> / <see cref="RemoveAsync"/> / <see cref="UpdateScheduleAsync"/>,
+/// and <see cref="ISupportsCronScheduling"/> before passing
+/// <see cref="DynamicBackgroundWorkerSchedule.CronExpression"/>.
+/// </para>
 /// </summary>
 public interface IDynamicBackgroundWorkerManager
 {
diff --git a/framework/test/Volo.Abp.BackgroundJobs.Tests/Volo/Abp/BackgroundWorkers/DynamicBackgroundWorkerManager_Tests.cs b/framework/test/Volo.Abp.BackgroundJobs.Tests/Volo/Abp/BackgroundWorkers/DynamicBackgroundWorkerManager_Tests.cs
index 0614192662..955b2104dd 100644
--- a/framework/test/Volo.Abp.BackgroundJobs.Tests/Volo/Abp/BackgroundWorkers/DynamicBackgroundWorkerManager_Tests.cs
+++ b/framework/test/Volo.Abp.BackgroundJobs.Tests/Volo/Abp/BackgroundWorkers/DynamicBackgroundWorkerManager_Tests.cs
@@ -262,6 +262,30 @@ public class DynamicBackgroundWorkerManager_Tests : BackgroundJobsTestBase
         });
     }
 
+    [Fact]
+    public async Task Should_Throw_When_CronExpression_Is_Set_On_UpdateSchedule()
+    {
+        var workerName = "dynamic-worker-" + Guid.NewGuid();
+
+        await _dynamicWorkerManager.AddAsync(
+            workerName,
+            new DynamicBackgroundWorkerSchedule { Period = 1000 },
+            (_, _) => Task.CompletedTask
+        );
+
+        await Assert.ThrowsAsync<AbpException>(async () =>
+        {
+            await _dynamicWorkerManager.UpdateScheduleAsync(
+                workerName,
+                new DynamicBackgroundWorkerSchedule
+                {
+                    Period = 1000,
+                    CronExpression = "0 */5 * * * *"
+                }
+            );
+        });
+    }
+
     [Fact]
     public async Task Should_Continue_Running_After_Handler_Throws_Exception()
     {