feat: Add Minimal API for dependent jobs

Author: linkdotnet

CHANGELOG.md

@@ -9,6 +9,19 @@ All notable changes to **NCronJob** will be documented in this file. The project
 ### Added
 - Ability to add a timezone for a "minimal job".
 - Run jobs automatically when a job either succeeded or failed allowing to model a job pipeline. By [@linkdotnet](https://github.com/linkdotnet).
+```csharp
+builder.Services.AddNCronJob(options =>
+{
+    options.AddJob<ImportData>(p => p.WithCronExpression("0 0 * * *")
+     .ExecuteWhen(
+        success: s => s.RunJob<TransformData>("Optional Parameter"),
+        faulted: s => s.RunJob<Notify>("Another Optional Parameter"));
+});
+```
+- Minimal API for instant jobs and job dependencies. By [@linkdotnet](https://github.com/linkdotnet).
+```csharp
+public void MyOtherMethod() => jobRegistry.RunInstantJob((MyOtherService service) => service.Do());
+```
 
 ### Changed
 - Replace `Microsoft.Extensions.Hosting` with `Microsoft.Extensions.Hosting.Abstractions` for better compatibility. Reported by [@chrisls121](https://github.com/chrisls121) in [#74](https://github.com/NCronJob-Dev/NCronJob/issues/74). Implemented by [@linkdotnet](https://github.com/linkdotnet).

README.md

@@ -176,6 +176,18 @@ builder.Services.AddNCronJob(options =>
 });
 ```
 
+You just want to trigger a service and don't want to define a whole new job? No problem! The Minimal API is available here as well:
+
+```csharp
+builder.Services.AddNCronJob(options =>
+{
+    options.AddJob<ImportData>(p => p.WithCronExpression("0 0 * * *")
+     .ExecuteWhen(
+        success: s => s.RunJob(async (ITransformer transformer) => await transformer.TransformDataAsync()),
+        faulted: s => s.RunJob(async (INotificationService notifier) => await notifier.NotifyAsync())
+});
+```
+
 ## Support & Contributing
 
 Thanks to all [contributors](https://github.com/NCronJob-Dev/NCronJob/graphs/contributors) and people that are creating

docs/features/minimal-api.md

@@ -91,3 +91,6 @@ The minimal API has some restrictions over the "full approach":
 
 ## Minimal API for instant Jobs
 The minimal API also supports instant jobs, for this check out the [Instant Jobs](instant-jobs.md) documentation.
+
+## Minimal API for dependent jobs
+The minimal API also supports dependent jobs, for this check out the [Dependent Jobs](model-dependencies.md#minimal-api) documentation.

docs/features/model-dependencies.md

@@ -16,7 +16,7 @@ Services.AddNCronJob(options =>
 Both `success` and `faulted` are optional so that you can define only one of them if needed. `RunJob` can be chained to allow multiple jobs to run after the completion of the main job.
 
 This allows very complex job dependencies to be defined in a simple and readable way.
-![dependencies](../assets/flow.png)
+![dependencies](../assets/flow.webp)
 
 ### Passing parameters to dependent jobs
 The `RunJob` method allows optional parameters to be passed to the dependent job. 
@@ -91,3 +91,29 @@ builder.Services.AddNCronJob(options =>
     options.AddJob<JobA>().ExecuteWhen(success: s => s.RunJob<JobB>());
 });
 ```
+
+## Minimal API
+The `ExecuteWhen` method can also be used in a [Minimal API](minimal-api.md) to define job dependencies:
+```csharp
+builder.Services.AddNCronJob(options => 
+{
+    options.AddJob<ImportDataJob>().ExecuteWhen(
+        success: s => s.RunJob(async (ITransfomerService transformerService) => await transformerService.TransformDataAsync()),
+        faulted: f => f.RunJob(async (INotificationService notificationService) => await notificationService.SendNotificationAsync()));
+});
+```
+
+### Getting the parent job's output in a Minimal API
+If you pass in a `JobExecutionContext` to the dependent job, you can access the parent job's output:
+
+```csharp
+builder.Services.AddNCronJob(options => 
+{
+    options.AddJob<ImportDataJob>().ExecuteWhen(
+        success: s => s.RunJob(async (JobExecutionContext context, ITransfomerService transformerService) => 
+        {
+            var parentOutput = (MyDataModel)context.ParentOutput;
+            await transformerService.TransformDataAsync(parentOutput);
+        }));
+});
+```

src/NCronJob/Configuration/DependencyBuilder.cs

@@ -1,3 +1,5 @@
+using Microsoft.Extensions.DependencyInjection;
+
 namespace NCronJob;
 
 /// <summary>
@@ -7,6 +9,9 @@ public sealed class DependencyBuilder<TPrincipalJob>
     where TPrincipalJob : IJob
 {
     private readonly List<JobDefinition> dependentJobOptions = [];
+    private readonly IServiceCollection services;
+
+    internal DependencyBuilder(IServiceCollection services) => this.services = services;
 
     /// <summary>
     /// Adds a job that runs after the principal job has finished with a given <paramref name="parameter"/>.
@@ -21,5 +26,23 @@ public DependencyBuilder<TPrincipalJob> RunJob<TJob>(object? parameter = null)
         return this;
     }
 
+    /// <summary>
+    /// Adds an anonymous delegate job that runs after the principal job has finished.
+    /// </summary>
+    /// <param name="jobDelegate">The delegate that represents the job to be executed. This delegate must return either void or Task.</param>
+    public DependencyBuilder<TPrincipalJob> RunJob(Delegate jobDelegate)
+    {
+        ArgumentNullException.ThrowIfNull(jobDelegate);
+
+        var jobPolicyMetadata = new JobExecutionAttributes(jobDelegate);
+        var entry = new JobDefinition(typeof(DynamicJobFactory), null, null, null,
+            JobName: DynamicJobNameGenerator.GenerateJobName(jobDelegate),
+            JobPolicyMetadata: jobPolicyMetadata);
+        dependentJobOptions.Add(entry);
+        services.AddSingleton(entry);
+        services.AddSingleton(new DynamicJobRegistration(entry, sp => new DynamicJobFactory(sp, jobDelegate)));
+        return this;
+    }
+
     internal List<JobDefinition> GetDependentJobOption() => dependentJobOptions;
 }

src/NCronJob/Configuration/DynamicJobFactory.cs

@@ -29,14 +29,14 @@ public DynamicJobFactory(IServiceProvider serviceProvider, Delegate jobAction)
             ).ToArray();
     }
 
-    private static Func<object[], Task> BuildInvoker(Delegate jobAction)
+    private static Func<object[], Task> BuildInvoker(Delegate jobDelegate)
     {
-        var method = jobAction.Method;
+        var method = jobDelegate.Method;
         var returnType = method.ReturnType;
         var param = Expression.Parameter(typeof(object[]), "args");
         var args = method.GetParameters().Select((p, index) =>
             Expression.Convert(Expression.ArrayIndex(param, Expression.Constant(index)), p.ParameterType)).ToArray();
-        var call = Expression.Call(Expression.Constant(jobAction.Target), method, args);
+        var call = Expression.Call(Expression.Constant(jobDelegate.Target), method, args);
 
         if (returnType == typeof(Task))
         {

src/NCronJob/Configuration/NCronJobOptionBuilder.cs

@@ -2,7 +2,6 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.DependencyInjection.Extensions;
 using System.Reflection;
-using System.Text;
 
 namespace NCronJob;
 
@@ -202,7 +201,7 @@ public INotificationStage<TJob> ExecuteWhen(Action<DependencyBuilder<TJob>>? suc
     {
         if (success is not null)
         {
-            var dependencyBuilder = new DependencyBuilder<TJob>();
+            var dependencyBuilder = new DependencyBuilder<TJob>(services);
             success(dependencyBuilder);
             var runWhenSuccess = dependencyBuilder.GetDependentJobOption();
             runWhenSuccess.ForEach(s =>
@@ -215,7 +214,7 @@ public INotificationStage<TJob> ExecuteWhen(Action<DependencyBuilder<TJob>>? suc
 
         if (faulted is not null)
         {
-            var dependencyBuilder = new DependencyBuilder<TJob>();
+            var dependencyBuilder = new DependencyBuilder<TJob>(services);
             faulted(dependencyBuilder);
             var runWhenFaulted = dependencyBuilder.GetDependentJobOption();
             runWhenFaulted.ForEach(s =>
@@ -279,7 +278,7 @@ public INotificationStage<TJob> ExecuteWhen(Action<DependencyBuilder<TJob>>? suc
     {
         if (success is not null)
         {
-            var dependencyBuilder = new DependencyBuilder<TJob>();
+            var dependencyBuilder = new DependencyBuilder<TJob>(services);
             success(dependencyBuilder);
             var runWhenSuccess = dependencyBuilder.GetDependentJobOption();
             runWhenSuccess.ForEach(s =>
@@ -292,7 +291,7 @@ public INotificationStage<TJob> ExecuteWhen(Action<DependencyBuilder<TJob>>? suc
 
         if (faulted is not null)
         {
-            var dependencyBuilder = new DependencyBuilder<TJob>();
+            var dependencyBuilder = new DependencyBuilder<TJob>(services);
             faulted(dependencyBuilder);
             var runWhenFaulted = dependencyBuilder.GetDependentJobOption();
             runWhenFaulted.ForEach(s =>

src/NCronJob/Registry/DynamicJobFactoryRegistry.cs

@@ -13,18 +13,25 @@ public DynamicJobFactoryRegistry(
         map = entries.ToDictionary(e => e.JobDefinition.JobFullName, v => v.DynamicJobFactoryResolver);
     }
 
-    public JobDefinition Add(Delegate jobAction)
+    public JobDefinition Add(Delegate jobDelegate)
     {
-        var jobPolicyMetadata = new JobExecutionAttributes(jobAction);
+        var jobPolicyMetadata = new JobExecutionAttributes(jobDelegate);
         var entry = new JobDefinition(typeof(DynamicJobFactory), null, null, null,
-            JobName: DynamicJobNameGenerator.GenerateJobName(jobAction),
+            JobName: DynamicJobNameGenerator.GenerateJobName(jobDelegate),
             JobPolicyMetadata: jobPolicyMetadata);
         jobRegistry.Add(entry);
-        map[entry.JobFullName] = serviceProvider => new DynamicJobFactory(serviceProvider, jobAction);
+        map[entry.JobFullName] = serviceProvider => new DynamicJobFactory(serviceProvider, jobDelegate);
 
         return entry;
     }
 
+    /// <summary>
+    /// Gets the job instance and removes it from the registry. The instance will be drained so that the Garbage Collector can collect it.
+    /// </summary>
+    /// <remarks>
+    /// This function is called for triggering instant jobs. As the time interval between executions can be long (to indefinite),
+    /// the job instance should be removed from the registry to prevent memory leaks.
+    /// </remarks>
     public IJob GetAndDrainJobInstance(IServiceProvider serviceProvider, JobDefinition jobDefinition)
     {
         var element = map[jobDefinition.JobFullName](serviceProvider);

src/NCronJob/Registry/IInstantJobRegistry.cs

@@ -29,11 +29,11 @@ void RunInstantJob<TJob>(object? parameter = null, CancellationToken token = def
     /// Runs an instant job, which gets directly executed.
     /// </summary>
     /// <remarks>
-    /// The <paramref name="jobAction"/> delegate supports, like <see cref="ServiceCollectionExtensions.AddNCronJob"/>, that services can be retrieved dynamically.
+    /// The <paramref name="jobDelegate"/> delegate supports, like <see cref="ServiceCollectionExtensions.AddNCronJob"/>, that services can be retrieved dynamically.
     /// Also the <see cref="CancellationToken"/> can be retrieved in this way.
     /// </remarks>
-    /// <param name="jobAction">The delegate to execute.</param>
-    void RunInstantJob(Delegate jobAction);
+    /// <param name="jobDelegate">The delegate to execute.</param>
+    void RunInstantJob(Delegate jobDelegate);
 
     /// <summary>
     /// Runs a job that will be executed after the given <paramref name="delay"/>.
@@ -47,13 +47,13 @@ void RunScheduledJob<TJob>(TimeSpan delay, object? parameter = null, Cancellatio
     /// <summary>
     /// Runs a job that will be executed after the given <paramref name="delay"/>.
     /// </summary>
-    /// <param name="jobAction">The delegate to execute.</param>
+    /// <param name="jobDelegate">The delegate to execute.</param>
     /// <param name="delay">The delay until the job will be executed.</param>
     /// <remarks>
-    /// The <paramref name="jobAction"/> delegate supports, like <see cref="ServiceCollectionExtensions.AddNCronJob"/>, that services can be retrieved dynamically.
+    /// The <paramref name="jobDelegate"/> delegate supports, like <see cref="ServiceCollectionExtensions.AddNCronJob"/>, that services can be retrieved dynamically.
     /// Also the <see cref="CancellationToken"/> can be retrieved in this way.
     /// </remarks>
-    void RunScheduledJob(Delegate jobAction, TimeSpan delay);
+    void RunScheduledJob(Delegate jobDelegate, TimeSpan delay);
 
     /// <summary>
     /// Runs a job that will be executed at <paramref name="startDate"/>.
@@ -67,13 +67,13 @@ void RunScheduledJob<TJob>(DateTimeOffset startDate, object? parameter = null, C
     /// <summary>
     /// Runs a job that will be executed at the given <paramref name="startDate"/>.
     /// </summary>
-    /// <param name="jobAction">The delegate to execute.</param>
+    /// <param name="jobDelegate">The delegate to execute.</param>
     /// <param name="startDate">The starting point when the job will be executed.</param>
     /// <remarks>
-    /// The <paramref name="jobAction"/> delegate supports, like <see cref="ServiceCollectionExtensions.AddNCronJob"/>, that services can be retrieved dynamically.
+    /// The <paramref name="jobDelegate"/> delegate supports, like <see cref="ServiceCollectionExtensions.AddNCronJob"/>, that services can be retrieved dynamically.
     /// Also the <see cref="CancellationToken"/> can be retrieved in this way.
     /// </remarks>
-    void RunScheduledJob(Delegate jobAction, DateTimeOffset startDate);
+    void RunScheduledJob(Delegate jobDelegate, DateTimeOffset startDate);
 }
 
 internal sealed partial class InstantJobRegistry : IInstantJobRegistry
@@ -102,7 +102,7 @@ public InstantJobRegistry(
     public void RunInstantJob<TJob>(object? parameter = null, CancellationToken token = default)
         where TJob : IJob => RunScheduledJob<TJob>(TimeSpan.Zero, parameter, token);
 
-    public void RunInstantJob(Delegate jobAction) => RunScheduledJob(jobAction, TimeSpan.Zero);
+    public void RunInstantJob(Delegate jobDelegate) => RunScheduledJob(jobDelegate, TimeSpan.Zero);
 
     /// <inheritdoc />
     public void RunScheduledJob<TJob>(TimeSpan delay, object? parameter = null, CancellationToken token = default)
@@ -112,10 +112,10 @@ public void RunScheduledJob<TJob>(TimeSpan delay, object? parameter = null, Canc
         RunScheduledJob<TJob>(utcNow + delay, parameter, token);
     }
 
-    public void RunScheduledJob(Delegate jobAction, TimeSpan delay)
+    public void RunScheduledJob(Delegate jobDelegate, TimeSpan delay)
     {
         var utcNow = timeProvider.GetUtcNow();
-        RunScheduledJob(jobAction, utcNow + delay);
+        RunScheduledJob(jobDelegate, utcNow + delay);
     }
 
     /// <inheritdoc />
@@ -135,9 +135,9 @@ public void RunScheduledJob<TJob>(DateTimeOffset startDate, object? parameter =
         jobQueue.EnqueueForDirectExecution(run, startDate);
     }
 
-    public void RunScheduledJob(Delegate jobAction, DateTimeOffset startDate)
+    public void RunScheduledJob(Delegate jobDelegate, DateTimeOffset startDate)
     {
-        var definition = dynamicJobFactoryRegistry.Add(jobAction);
+        var definition = dynamicJobFactoryRegistry.Add(jobDelegate);
         var run = JobRun.Create(definition);
         run.Priority = JobPriority.High;
 

tests/NCronJob.Tests/RunDependentJobTests.cs

@@ -83,6 +83,24 @@ public async Task SkipChildrenShouldPreventDependentJobsFromRunning()
         storage.Guids.Count.ShouldBe(1);
     }
 
+    [Fact]
+    public async Task WhenJobWasSuccessful_DependentAnonymousJobShouldRun()
+    {
+        var fakeTimer = new FakeTimeProvider();
+        ServiceCollection.AddSingleton<TimeProvider>(fakeTimer);
+        Func<ChannelWriter<object>, JobExecutionContext, Task> execution = async (writer, context) => await writer.WriteAsync($"Parent: {context.ParentOutput}");
+        ServiceCollection.AddNCronJob(n => n.AddJob<PrincipalJob>()
+            .ExecuteWhen(success: s => s.RunJob(execution)));
+        var provider = CreateServiceProvider();
+        await provider.GetRequiredService<IHostedService>().StartAsync(CancellationToken);
+
+        provider.GetRequiredService<IInstantJobRegistry>().RunInstantJob<PrincipalJob>(true);
+
+        using var tcs = new CancellationTokenSource(TimeSpan.FromMilliseconds(500));
+        var result = await CommunicationChannel.Reader.ReadAsync(tcs.Token) as string;
+        result.ShouldBe("Parent: Success");
+    }
+
     private sealed class PrincipalJob : IJob
     {
         public Task RunAsync(JobExecutionContext context, CancellationToken token)