Merge pull request #10 from Anders-Toegersen/feature/backgroundservicebase-overhaul

Feature: BackgroundServiceBase & BackgroundServiceHealthService Overhaul

Author: Anders-Toegersen

README.md

@@ -2,7 +2,7 @@
 
 # Atc.Hosting
 
-The Atc.Hosting namespace serves as a toolbox for building scalable and reliable hosting solutions, with an emphasis on background services. It contains classes and extension methods designed to handle common hosting scenarios, providing enhanced features like custom logging, retries, and advanced configuration options. The namespace aims to streamline development efforts and improve the maintainability of hosted applications.
+The Atc.Hosting namespace serves as a toolbox for building scalable and reliable hosting solutions, with an emphasis on background services. It contains classes and extension methods designed to handle common hosting scenarios, providing enhanced features like custom logging, and advanced configuration options. The namespace aims to streamline development efforts and improve the maintainability of hosted applications.
 
 # Table of Contents
 
@@ -11,7 +11,6 @@ The Atc.Hosting namespace serves as a toolbox for building scalable and reliable
 - [BackgroundServiceBase`<T>`](#backgroundservicebaset)
   - [Features](#features)
     - [Logging](#logging)
-    - [Retry Mechanism](#retry-mechanism)
     - [Error Handling](#error-handling)
     - [Configuration Options](#configuration-options)
     - [Ease of Use](#ease-of-use)
@@ -32,8 +31,7 @@ The Atc.Hosting namespace serves as a toolbox for building scalable and reliable
 
 # BackgroundServiceBase`<T>`
 
-The `BackgroundServiceBase<T>` class serves as a base for background services that require enhanced features like custom logging, retries, and configurable service options. It extends the ASP.NET Core's `BackgroundService` class, providing a more robust framework for handling 
-background tasks.
+The `BackgroundServiceBase<T>` class serves as a base for continuous long running background services that require enhanced features like custom logging and configurable service options. It extends the ASP.NET Core's `BackgroundService` class, providing a more robust framework for handling background tasks.
 
 ## Features
 
@@ -42,20 +40,16 @@ background tasks.
 - Utilizes `ILogger<T>` for type-specific, high-performance logging.
 - Automatically enriches log entries with the name of the service type (`T`).
 
-### Retry Mechanism
-
-- Built-in retries using the `Polly` library.
-- Retry count and exponential backoff settings are configurable.
-
 ### Error Handling
 
-- Catches exceptions and logs them with a severity of `LogLevel.Warning`.
+- Catches unhandled exceptions and logs them with a severity of `LogLevel.Warning`.
+- Reruns the `DoWorkAsync` method after a configurable repeat interval.
+- For manual error handling hook into the exception handling in `DoWorkAsync` by overriding the `OnExceptionAsync` method.
 - Designed to log errors rather than crashing the service.
 
 ### Configuration Options
 
 - Allows for startup delays.
-- Configurable retry count.
 - Configurable repeat interval for running tasks.
 
 ### Ease of Use
@@ -184,6 +178,23 @@ public override async Task DoWorkAsync(CancellationToken stoppingToken)
 }
 ```
 
+## Default implementation for `BackgroundServiceBase<>`
+The `BackgroundServiceBase<>` automatically uses the `IBackgroundServiceHealthService` in the `DoWorkAsync` 'wait and retry' loop. This is archieved by providing the base constructor with a `IBackgroundServiceHealthService` instance.
+
+```csharp
+public TimeFileWorker(
+    //...other parameters
+    IBackgroundServiceHealthService healthService,
+    //...other parameters 
+    ) 
+    : base (healthService)
+{
+    //...other initializations
+}
+```
+
+Now you not have to set the running state of the service in the `BackgroundService.StartAsync` and `BackgroundService.StopAsync` methods.
+
 # Complete TimeFileWorker example
 
 A sample reference implementation can be found in the sample project [`Atc.Hosting.TimeFile.Sample`](sample/Atc.Hosting.TimeFile.Sample/Program.cs)
@@ -192,7 +203,6 @@ which shows an example of the service `TimeFileWorker` that uses `BackgroundServ
 ```csharp
 public class TimeFileWorker : BackgroundServiceBase<TimeFileWorker>
 {
-    private readonly IBackgroundServiceHealthService healthService;
     private readonly ITimeProvider timeProvider;
 
     private readonly TimeFileWorkerOptions workerOptions;
@@ -204,28 +214,26 @@ public class TimeFileWorker : BackgroundServiceBase<TimeFileWorker>
         IOptions<TimeFileWorkerOptions> workerOptions)
         : base(
             logger,
-            workerOptions.Value)
+            workerOptions.Value,
+            healthService)
     {
-        this.healthService = healthService;
         this.timeProvider = timeProvider;
         this.workerOptions = workerOptions.Value;
     }
 
-    public override async Task StartAsync(
+    public override Task StartAsync(
         CancellationToken cancellationToken)
     {
-        await base.StartAsync(cancellationToken);
-        healthService.SetRunningState(nameof(TimeFileWorker), isRunning: true);
+        return base.StartAsync(cancellationToken);
     }
 
-    public override async Task StopAsync(
+    public override Task StopAsync(
         CancellationToken cancellationToken)
     {
-        await base.StopAsync(cancellationToken);
-        healthService.SetRunningState(nameof(TimeFileWorker), isRunning: false);
+        return base.StopAsync(cancellationToken);
     }
 
-    public override async Task DoWorkAsync(
+    public override Task DoWorkAsync(
         CancellationToken stoppingToken)
     {
         var isServiceRunning = healthService.IsServiceRunning(nameof(TimeFileWorker));
@@ -238,9 +246,20 @@ public class TimeFileWorker : BackgroundServiceBase<TimeFileWorker>
             workerOptions.OutputDirectory,
             $"{time:yyyy-MM-dd--HHmmss}-{isServiceRunning}.txt");
 
-        await File.WriteAllTextAsync(outFile, $"{ServiceName}-{isServiceRunning}", stoppingToken);
+        return File.WriteAllTextAsync(outFile, $"{ServiceName}-{isServiceRunning}", stoppingToken);
+    }
+
+    protected override Task OnExceptionAsync(
+        Exception exception,
+        CancellationToken stoppingToken)
+    {
+        if (exception is IOException or UnauthorizedAccessException)
+        {
+            logger.LogCritical(exception, "Could not write file!");
+            return StopAsync(stoppingToken);
+        }
 
-        healthService.SetRunningState(nameof(TimeFileWorker), isRunning: true);
+        return base.OnExceptionAsync(exception, stoppingToken);
     }
 }
 ```

sample/.editorconfig

@@ -49,4 +49,5 @@
 dotnet_diagnostic.CA1062.severity = none            # Validate arguments of public methods
 dotnet_diagnostic.CA1852.severity = none            # Seal internal types
 
-dotnet_diagnostic.MA0076.severity = none            # Do not use implicit culture-sensitive ToString in interpolated strings
+dotnet_diagnostic.MA0076.severity = none            # Do not use implicit culture-sensitive ToString in interpolated strings
+dotnet_diagnostic.CA1848.severity = none            # Performance logging

sample/Atc.Hosting.TimeFile.Sample/TimeFileWorker.cs

@@ -2,7 +2,6 @@ namespace Atc.Hosting.TimeFile.Sample;
 
 public class TimeFileWorker : BackgroundServiceBase<TimeFileWorker>
 {
-    private readonly IBackgroundServiceHealthService healthService;
     private readonly ITimeProvider timeProvider;
 
     private readonly TimeFileWorkerOptions workerOptions;
@@ -14,28 +13,26 @@ public TimeFileWorker(
         IOptions<TimeFileWorkerOptions> workerOptions)
         : base(
             logger,
-            workerOptions.Value)
+            workerOptions.Value,
+            healthService)
     {
-        this.healthService = healthService;
         this.timeProvider = timeProvider;
         this.workerOptions = workerOptions.Value;
     }
 
-    public override async Task StartAsync(
+    public override Task StartAsync(
         CancellationToken cancellationToken)
     {
-        await base.StartAsync(cancellationToken);
-        healthService.SetRunningState(nameof(TimeFileWorker), isRunning: true);
+        return base.StartAsync(cancellationToken);
     }
 
-    public override async Task StopAsync(
+    public override Task StopAsync(
         CancellationToken cancellationToken)
     {
-        await base.StopAsync(cancellationToken);
-        healthService.SetRunningState(nameof(TimeFileWorker), isRunning: false);
+        return base.StopAsync(cancellationToken);
     }
 
-    public override async Task DoWorkAsync(
+    public override Task DoWorkAsync(
         CancellationToken stoppingToken)
     {
         var isServiceRunning = healthService.IsServiceRunning(nameof(TimeFileWorker));
@@ -48,8 +45,19 @@ public override async Task DoWorkAsync(
             workerOptions.OutputDirectory,
             $"{time:yyyy-MM-dd--HHmmss}-{isServiceRunning}.txt");
 
-        await File.WriteAllTextAsync(outFile, $"{ServiceName}-{isServiceRunning}", stoppingToken);
+        return File.WriteAllTextAsync(outFile, $"{ServiceName}-{isServiceRunning}", stoppingToken);
+    }
+
+    protected override Task OnExceptionAsync(
+        Exception exception,
+        CancellationToken stoppingToken)
+    {
+        if (exception is IOException or UnauthorizedAccessException)
+        {
+            logger.LogCritical(exception, "Could not write file!");
+            return StopAsync(stoppingToken);
+        }
 
-        healthService.SetRunningState(nameof(TimeFileWorker), isRunning: true);
+        return base.OnExceptionAsync(exception, stoppingToken);
     }
 }

sample/Atc.Hosting.TimeFile.Sample/TimeFileWorkerOptions.cs

@@ -8,10 +8,8 @@ public class TimeFileWorkerOptions : IBackgroundServiceOptions
 
     public ushort StartupDelaySeconds { get; set; } = 1;
 
-    public ushort RetryCount { get; set; } = 3;
-
     public ushort RepeatIntervalSeconds { get; set; } = 20;
 
     public override string ToString()
-        => $"{nameof(OutputDirectory)}: {OutputDirectory}, {nameof(StartupDelaySeconds)}: {StartupDelaySeconds}, {nameof(RetryCount)}: {RetryCount}, {nameof(RepeatIntervalSeconds)}: {RepeatIntervalSeconds}";
+        => $"{nameof(OutputDirectory)}: {OutputDirectory}, {nameof(StartupDelaySeconds)}: {StartupDelaySeconds}, {nameof(RepeatIntervalSeconds)}: {RepeatIntervalSeconds}";
 }

src/Atc.Hosting/Atc.Hosting.csproj

@@ -17,7 +17,6 @@
     <PackageReference Include="Atc" Version="2.0.349" />
     <PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" Version="7.0.0" />
     <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="7.0.1" />
-    <PackageReference Include="Polly" Version="7.2.3" />
   </ItemGroup>
 
 </Project>