Teach AddNCronJob() to accept a JobOptionBuilder

Author: nulltoken

sample/MinimalSample/Program.cs

@@ -3,7 +3,7 @@
 var builder = Host.CreateApplicationBuilder(args);
 
 builder.Services.AddNCronJob((ILogger<Program> logger, TimeProvider timeProvider) =>
-    logger.LogInformation("Hello World - The current date and time is {Time}", timeProvider.GetLocalNow())
-    , "*/5 * * * * *");
+    logger.LogInformation("Hello World - The current date and time is {Time}", timeProvider.GetLocalNow()),
+    p => p.WithCronExpression("*/5 * * * * *"));
 
 await builder.Build().RunAsync();

src/NCronJob/NCronJobExtensions.cs

@@ -120,10 +120,58 @@ public static IServiceCollection AddNCronJob(
     ///         </code>
     ///     </example>
     /// <returns>The modified service collection.</returns>
+    [Obsolete("This method will be dropped in the next major version. Register untyped jobs using AddNCronJob(Delegate, Action<JobOptionBuilder>) overload instead.")]
     public static IServiceCollection AddNCronJob(this IServiceCollection services, Delegate jobDelegate, string cronExpression, TimeZoneInfo? timeZoneInfo = null)
-#pragma warning disable CS0618 // Type or member is obsolete
-        => services.AddNCronJob(builder => builder.AddJob(jobDelegate, cronExpression, timeZoneInfo));
-#pragma warning restore CS0618 // Type or member is obsolete
+        => services.AddNCronJob(jobDelegate, p => p.WithCronExpression(cronExpression, timeZoneInfo));
+
+    /// <summary>
+    /// Adds a job using an anonymous delegate to the service collection that gets executed based on the given cron expression.
+    /// This method allows for the scheduling of either synchronous or asynchronous tasks which are defined using lambda expressions.
+    /// The delegate can depend on services registered in the dependency injection container, which are resolved at runtime.
+    /// </summary>
+    /// <param name="services">The service collection used to register the services.</param>
+    /// <param name="jobDelegate">The delegate that represents the job to be executed. This delegate must return either void or Task.</param>
+    /// <param name="options">The options that define how the job should be executed.</param>
+    ///     <example>
+    ///         Synchronous job example:
+    ///         <code>
+    ///             builder.Services.AddNCronJob((ILogger&lt;Program&gt; logger, TimeProvider timeProvider) =&gt;
+    ///             {
+    ///                 logger.LogInformation("Hello World - The current date and time is {Time}", timeProvider.GetLocalNow());
+    ///             }, p => p.WithCronExpression("*/40 * * * * *"));
+    ///         </code>
+    ///         Asynchronous job example:
+    ///         <code>
+    ///             builder.Services.AddNCronJob(async (ILogger&lt;Program&gt; logger, TimeProvider timeProvider, CancellationToken ct) =&gt;
+    ///             {
+    ///                 logger.LogInformation("Hello World - The current date and time is {Time}", timeProvider.GetLocalNow());
+    ///                 await Task.Delay(1000, ct);
+    ///             }, p => p.WithCronExpression("*/40 * * * * *"));
+    ///         </code>
+    ///         Synchronous job with retry policy example:
+    ///         <code>
+    ///             builder.Services.AddNCronJob([RetryPolicy(retryCount: 4)] (JobExecutionContext context, ILogger&lt;Program&gt; logger) =&gt;
+    ///             {
+    ///                 var attemptCount = context.Attempts;
+    ///                 if (attemptCount &lt;= 4)
+    ///                 {
+    ///                     logger.LogWarning("TestRetryJob simulating failure.");
+    ///                     throw new InvalidOperationException("Simulated operation failure in TestRetryJob.");
+    ///                 }
+    ///                 logger.LogInformation($"Job ran after {attemptCount} attempts");
+    ///             }, p => p.WithCronExpression("*/5 * * * * *"));
+    ///         </code>
+    ///         Synchronous job example with TimeZone:
+    ///         <code>
+    ///             builder.Services.AddNCronJob((ILogger&lt;Program&gt; logger, TimeProvider timeProvider) =&gt;
+    ///             {
+    ///                 logger.LogInformation("Hello World - The current date and time is {Time}", timeProvider.GetLocalNow());
+    ///             }, p => p.WithCronExpression("*/40 * * * * *", TimeZoneInfo.FindSystemTimeZoneById("Pacific Standard Time")));
+    ///         </code>
+    ///     </example>
+    /// <returns>The modified service collection.</returns>
+    public static IServiceCollection AddNCronJob(this IServiceCollection services, Delegate jobDelegate, Action<JobOptionBuilder> options)
+        => services.AddNCronJob(builder => builder.AddJob(jobDelegate, options));
 
     /// <summary>
     /// Configures the host to use NCronJob. This will also start any given startup jobs and their dependencies.

tests/NCronJob.Tests/IntegrationTests.cs

@@ -528,7 +528,7 @@ public async Task MinimalJobApiCanBeUsedForTriggeringCronJobs()
         ServiceCollection.AddNCronJob((Storage storage) =>
         {
             storage.Add("Done");
-        }, Cron.AtEveryMinute);
+        }, p => p.WithCronExpression(Cron.AtEveryMinute));
 
         await StartNCronJob(startMonitoringEvents: true);