feat: Add Notification System when job is done

Author: linkdotnet

.editorconfig

@@ -442,11 +442,7 @@ dotnet_diagnostic.CA2201.severity = suggestion # CA2201: Do not raise reserved e
 
 # SonarAnalyzer.CSharp
 # https://rules.sonarsource.com/csharp
-dotnet_diagnostic.S112.severity = none # S112: General exceptions should never be thrown
-dotnet_diagnostic.S1075.severity = suggestion # S1075: URIs should not be hardcoded
-dotnet_diagnostic.S1186.severity = suggestion # S1186: Methods should not be empty
-dotnet_diagnostic.S2292.severity = suggestion # S2292: Trivial properties should be auto-implemented
-dotnet_diagnostic.S4158.severity = none # BUGGY with C#9 code - doesnt understand local methods
+dotnet_diagnostic.S2326.severity = none # S2326: Unused type parameters should be removed
 
 ##########################################
 # Custom Test Code Analyzers Rules
@@ -456,16 +452,6 @@ dotnet_diagnostic.S4158.severity = none # BUGGY with C#9 code - doesnt understan
 # Visual Studio
 csharp_style_pattern_local_over_anonymous_function = false # IDE0039: Use local function
 
-# AsyncFixer
-# http://www.asyncfixer.com
-dotnet_diagnostic.AsyncFixer01.severity = none # AsyncFixer01: Unnecessary async/await usage
-
-# Meziantou
-# https://www.meziantou.net/enforcing-asynchronous-code-good-practices-using-a-roslyn-analyzer.htm
-dotnet_diagnostic.MA0006.severity = suggestion # MA0006: use String.Equals
-dotnet_diagnostic.MA0007.severity = none # MA0007: Add a comma after the last value
-dotnet_diagnostic.MA0048.severity = silent # MA0048: File name must match type name
-
 # Microsoft - Code Analysis
 # https://docs.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/
 dotnet_diagnostic.CA1054.severity = none # CA1054: URI-like parameters should not be strings

CHANGELOG.md

@@ -11,6 +11,7 @@ All notable changes to **NCronJob** will be documented in this file. The project
 -   Ability to set cron expressions with second-level precision
 -   Support for `net9.0`
 -   Support for Isolation Level to run jobs independent of the current scheduler
+-   Notification system that allows to run a task when a job is finished
 
 ## [0.10.1] - 2024-03-19
 

README.md

@@ -14,7 +14,7 @@
 # NCronJob
 A Job Scheduler sitting on top of `IHostedService` in dotnet.
 
-Often times one finds themself between the simplicisty of the `BackgroundService`/`IHostedService` and the complexity of a full blown `Hangfire` or `Quartz` scheduler. 
+Often times one finds themself between the simplicity of the `BackgroundService`/`IHostedService` and the complexity of a full blown `Hangfire` or `Quartz` scheduler. 
 This library aims to fill that gap by providing a simple and easy to use job scheduler that can be used in any dotnet application and feels "native".
 
 So no need for setting up a database, just schedule your stuff right away! The library gives you two ways of scheduling jobs:
@@ -26,7 +26,7 @@ So no need for setting up a database, just schedule your stuff right away! The l
 - [x] The ability to instantly run a job
 - [x] Parameterized jobs - instant as well as cron jobs!
 - [x] Integrated in ASP.NET - Access your DI container like you would in any other service
-- [ ] Get notified when a job is done (either successfully or with an error) - currently in development
+- [x] Get notified when a job is done (either successfully or with an error).
 
 ## Not features
 
@@ -91,6 +91,42 @@ public class MyService
 }
 ```
 
+## Getting notified when a job is done
+**NCronJob** provides a way to get notified when a job is done. For this, implement a `IJobNotificationHandler<TJob>` and register it in your DI container.
+```csharp
+Services.AddNotificationHandler<MyJobNotificationHandler, MyJob>();
+```
+
+This allows to run logic after a job is done. The `JobExecutionContext` and the `Exception` (if there was one) are passed to the `Handle` method.
+
+```csharp
+public class MyJobNotificationHandler : IJobNotificationHandler<MyJob>
+{
+	private readonly ILogger<MyJobNotificationHandler> logger;
+
+	public MyJobNotificationHandler(ILogger<MyJobNotificationHandler> logger)
+	{
+		this.logger = logger;
+	}
+
+	public Task HandleAsync(JobExecutionContext context, Exception? exception, CancellationToken token)
+	{
+		if (exception is not null)
+		{
+			logger.LogError(exception, "Job failed");
+		}
+		else
+		{
+			logger.LogInformation("Job was successful");
+			logger.LogInformation("Output: {Output}", context.Output);
+		}
+
+		return Task.CompletedTask;
+	}
+}
+```
+
+
 ## Advanced Cases
 
 ### Isolation Level

sample/NCronJobSample/HelloWorldJobHandler.cs

@@ -0,0 +1,24 @@
+using LinkDotNet.NCronJob;
+
+namespace NCronJobSample;
+
+public partial class HelloWorldJobHandler : IJobNotificationHandler<PrintHelloWorldJob>
+{
+    private readonly ILogger<HelloWorldJobHandler> logger;
+
+    public HelloWorldJobHandler(ILogger<HelloWorldJobHandler> logger)
+    {
+        this.logger = logger;
+    }
+
+    public Task HandleAsync(JobExecutionContext context, Exception? exception, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+
+        LogMessage(context.Output);
+        return Task.CompletedTask;
+    }
+
+    [LoggerMessage(LogLevel.Information, "PrintHelloWorldJob is done and outputs: {Output}")]
+    private partial void LogMessage(object? output);
+}

sample/NCronJobSample/PrintHelloWorld.cs renamed to sample/NCronJobSample/PrintHelloWorldJob.cs

@@ -2,11 +2,11 @@
 
 namespace NCronJobSample;
 
-public partial class PrintHelloWorld : IJob
+public partial class PrintHelloWorldJob : IJob
 {
-    private readonly ILogger<PrintHelloWorld> logger;
+    private readonly ILogger<PrintHelloWorldJob> logger;
 
-    public PrintHelloWorld(ILogger<PrintHelloWorld> logger)
+    public PrintHelloWorldJob(ILogger<PrintHelloWorldJob> logger)
     {
         this.logger = logger;
     }
@@ -17,6 +17,8 @@ public Task Run(JobExecutionContext context, CancellationToken token = default)
 
         LogMessage(context.Parameter);
 
+        context.Output = "Hey there!";
+
         return Task.CompletedTask;
     }
 

sample/NCronJobSample/Program.cs

@@ -16,12 +16,15 @@
 });
 
 // Execute the job every minute
-builder.Services.AddCronJob<PrintHelloWorld>(p =>
+builder.Services.AddCronJob<PrintHelloWorldJob>(p =>
 {
     p.CronExpression = "* * * * *";
     p.Parameter = "Hello from NCronJob";
 });
 
+// Register a handler that gets executed when the job is done
+builder.Services.AddNotificationHandler<HelloWorldJobHandler, PrintHelloWorldJob>();
+
 var app = builder.Build();
 
 // Configure the HTTP request pipeline.
@@ -35,7 +38,7 @@
 
 app.MapPost("/trigger-instant", (IInstantJobRegistry instantJobRegistry) =>
     {
-        instantJobRegistry.AddInstantJob<PrintHelloWorld>("Hello from instant job!");
+        instantJobRegistry.AddInstantJob<PrintHelloWorldJob>("Hello from instant job!");
     })
     .WithName("TriggerInstantJob")
     .WithOpenApi();

src/LinkDotNet.NCronJob/IJobNotificationHandler.cs

@@ -0,0 +1,22 @@
+namespace LinkDotNet.NCronJob;
+
+/// <summary>
+/// Classes implementing this interface can handle the notification of a job execution.
+/// </summary>
+public interface IJobNotificationHandler
+{
+    /// <summary>
+    /// This method is invoked when a <see cref="IJob"/> is finished (either successfully or with an exception).
+    /// </summary>
+    /// <param name="context">The <see cref="JobExecutionContext"/> that was used for this run.</param>
+    /// <param name="exception">The exception that was thrown during the execution of the job. If the job was successful, this will be <c>null</c>.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> that can be used to cancel the notification.</param>
+    /// <remarks>
+    /// The method will be invoked with the same scope as the job itself.
+    /// </remarks>
+    Task HandleAsync(JobExecutionContext context, Exception? exception, CancellationToken cancellationToken);
+}
+
+/// <inheritdoc />
+public interface IJobNotificationHandler<TJob> : IJobNotificationHandler
+    where TJob : IJob;

src/LinkDotNet.NCronJob/JobExecutionContext.cs

@@ -4,4 +4,10 @@ namespace LinkDotNet.NCronJob;
 /// Represents the context of a job execution.
 /// </summary>
 /// <param name="Parameter">The passed in parameters to a job</param>
-public sealed record JobExecutionContext(object? Parameter);
+public sealed record JobExecutionContext(object? Parameter)
+{
+    /// <summary>
+    /// The output of a job that can be read by the <see cref="IJobNotificationHandler{TJob}"/>.
+    /// </summary>
+    public object? Output { get; set; }
+}

src/LinkDotNet.NCronJob/NCronJobExtensions.cs

@@ -59,6 +59,24 @@ public static IServiceCollection AddCronJob<T>(this IServiceCollection services,
         return services;
     }
 
+    /// <summary>
+    /// Adds a notification handler for a given <see cref="IJob"/>.
+    /// </summary>
+    /// <param name="services">The service collection used to register the handler.</param>
+    /// <typeparam name="TJobNotificationHandler">The handler-type that is used to handle the job.</typeparam>
+    /// <typeparam name="TJob">The job type.</typeparam>
+    /// <remarks>
+    /// The given <see cref="IJobNotificationHandler{TJob}"/> instance is registered as a scoped service sharing the same scope as the job.
+    /// Also only one handler per job is allowed. If multiple handlers are registered, only the first one will be executed.
+    /// </remarks>
+    public static IServiceCollection AddNotificationHandler<TJobNotificationHandler, TJob>(this IServiceCollection services)
+        where TJobNotificationHandler : class, IJobNotificationHandler<TJob>
+        where TJob : class, IJob
+    {
+        services.TryAddScoped<IJobNotificationHandler<TJob>, TJobNotificationHandler>();
+        return services;
+    }
+
     private static CrontabSchedule GetCronExpression(IServiceCollection services, JobOption option)
     {
         using var serviceProvider = services.BuildServiceProvider();

src/LinkDotNet.NCronJob/Scheduler/CronScheduler.cs

@@ -33,6 +33,8 @@ protected override async Task ExecuteAsync(CancellationToken stoppingToken)
         var runs = new List<Run>();
         while (await tickTimer.WaitForNextTickAsync(stoppingToken).ConfigureAwait(false))
         {
+            // We don't want to await jobs explicitly because that
+            // could interfere with other job runs)
             RunActiveJobs(runs, stoppingToken);
             runs = GetNextJobRuns();
         }
@@ -46,13 +48,51 @@ private void RunActiveJobs(List<Run> runs, CancellationToken stoppingToken)
             var scope = serviceProvider.CreateScope();
             var job = (IJob)scope.ServiceProvider.GetRequiredService(run.Type);
 
-            // We don't want to await jobs explicitly because that
-            // could interfere with other job runs)
-            var jobTask = run.IsolationLevel == IsolationLevel.None
+            RunJob(run, job, scope, stoppingToken);
+        }
+    }
+
+    private static void RunJob(Run run, IJob job, IServiceScope serviceScope, CancellationToken stoppingToken)
+    {
+        try
+        {
+            GetJobTask()
+                .ContinueWith(
+                    task => AfterJobCompletionTask(task.Exception),
+                    TaskScheduler.Current)
+                .ConfigureAwait(false);
+        }
+        catch (Exception exc) when (exc is not OperationCanceledException or AggregateException)
+        {
+            // This part is only reached if the synchronous part of the job throws an exception
+            AfterJobCompletionTask(exc);
+        }
+
+        Task GetJobTask()
+        {
+            return run.IsolationLevel == IsolationLevel.None
                 ? job.Run(run.Context, stoppingToken)
                 : Task.Run(() => job.Run(run.Context, stoppingToken), stoppingToken);
+        }
+
+        void AfterJobCompletionTask(Exception? exc)
+        {
+            var notificationServiceType = typeof(IJobNotificationHandler<>).MakeGenericType(run.Type);
+
+            if (serviceScope.ServiceProvider.GetService(notificationServiceType) is IJobNotificationHandler notificationService)
+            {
+                try
+                {
+                    notificationService.HandleAsync(run.Context, exc, stoppingToken).ConfigureAwait(false);
+                }
+                catch (Exception innerExc) when (innerExc is not OperationCanceledException or AggregateException)
+                {
+                    // We don't want to throw exceptions from the notification service
+                }
+
+            }
 
-            jobTask.ContinueWith(_ => scope.Dispose(), TaskScheduler.Current).ConfigureAwait(false);
+            serviceScope.Dispose();
         }
     }